تعلم API من خلال شرح دوال API مدعماً بالأمثلة
API – Windows Application Programming Interface
سأشرح في هذه الفقرة API بصورة عامة. أن الفائدة من أستخدام دوالAPI لسببين هما الأول نستطيع أنجاز قسم أشياء لاتستطيع لغة VB أنجازها، والثاني تستطيع تنفيذ بعض الأشياء أسرع من تنفيذها ب VB .
أستخدام API :
هناك أربعة خطوات لأستخدام دوال API
1- حدد أي برنامج فرعي تريد أن تستخدمه
هنالك دوال عديدة ل API وهي موضحة في Help الموجود في VB6.0 .
2- حدد هوية أو نوع البيانات التي ترغب بتمريرها الى البرنامج الفرعي . والعبارة TYPE تقوم بعملية التمرير.
3- تثبيت أو تعريغ Declare البرنامج الفرعي بأستخدام العبارة Declare ، للعلم API هو ليس جزء من لغة VB لهذا السبب تستخدم عبارة Declare لغرض أخبار VB أين يستطيع أن يجد هذه الدوال. والصيغة لعبارة التثبيت هي:
Declare Sub name lib "lib" [ Alias, "alias"] (arguments)
Declare Function name Lib "Lib" [Alias, "alias"] (arguments) As type
name : هو أسم الدالة التي تحددها
lib : موقع وجود المكتبة library وعلى سبيل المثال أسم المكتبة gdi32 ، kernel32 ، user32 ،....ألخ
alias :هي أسم الدلالة حيث يتم عن طريقها تعريف البرنامج الفرعي أو الدالة في المكتبة
arguments : هي أسم المتغيرات المستقلة المستخدمة من قبل دالة API التي تعرف بعبارة TYPE .
type : نوع المتغير المرجع لدالة API .
تمرير المتغيرات المستقلة Arguments :
لغة VB بصورة أساسية تمرر المتغيرات أستناداً الى المرجع ، أي بمعنى VB تمرر عناويين الذاكرة المخزونة فيها هذه المتغيرات يدلاً من تمرير قيمة المتغيير ، فلهاذا سنلاحظ كثيراً أستخدام ByVal وذلك لتغيير أسلوب التمرير للتمرير بقيمة المتغيير.
الجزم strings :
عند تمرير الحزم يجب أن تمرر باسلوب التمرير بالقيمة دائماً أي أستخدام ByVal
القيم Null :
عند عدم تثبيت قيمة المتغيير الحزمي فأن حالة API ستمرر القيمة البدائية Null بدلاً عن أنه فارغ . وهناك شئ أخر يجب عمله قبل تعريف دوال API المستخدمة مع الحزم وهو تعريف حجم الحيز الخاص بالحزمة عن طريق أستخدام DIM ، مثال DIM txt As String * 256 .
المناولة Handles :
كثير من دوال API تستخدم المناولة في برنامجها الفرعي لتمثيل عناصرها. ومنها مناولة التي تشير للويندوز HWND ، مناول الصور HBITMAP ومناولة تحديد الجهاز HDC .......ألخ. المناولات هي لاشئ سوى أنها أعداد صحيحة تمثل العنصر وعند أستخدامها من قبل دالة API يجب تعريفها على أنها ByVal Long وهي فقط أرقام وليست لها معنى أذا أستعملت خارج الجالة.
4- أستدعاء الدالة أو البرنامج الفرعي call routine :
بعد الأنتهاء من تعريف المحتويات أو البيانات يجب تثبيت دالة API ويتم أستدعائها كما تستدعى أي دالة أعتيادية في VB .
ومن خلال الأمثلة سأحاول شرح معظم دوال API الأكثر أستعمالاً والتي سوف تستفاد منها في تطوير برامجك.
المثال الأول : جعل الفورم ذات شفافية . من الممكن أنكم لاحظتم من لديه نظام التشغيل ويندوز 2000 و XP أنها تمتلك بعض النوافذ تمتلك شفافية تستطيع من خلالها رؤية ماموجود تحتها. لذا غي هذا المثال سأبرمج هذه الخاصية بأستعمال دوال API مع شرح كل دالة .
سيتكون البرنامج من فورم أسمه frmMain يتكون من عنصريين HScrollBar أسمه scrTransparancy و Label أسمه lblStatus ، أما الموجل Modules أسمه modTransparant
الدوال المستخدمة:
SetLayeredWindowAttributes : دالة تستخدم لأعداد عدم الشفافية والألوان الرئيسية للويندوز ذات الطبقات.
Private Declare Function SetLayeredWindowAttributes Lib "user32" (ByVal hWnd As Long, ByVal crKey As Long, ByVal bAlpha As Byte, ByVal dwFlags As Long) As Long
hwnd
مناولة إلى النافذةِ ذات الطبقاتِ. أي صفّفَ النافذةَ المَخْلُوقةُ بتَحديد WS_EX_LAYERED متى َخْلقُ النافذةَ بدالة CreateWindowEx أَو بوضع WS_EX_LAYERED عن طريق SetWindowLong بعد خُلِق النافذةِ .
crKey
تركيب Colorref الذي يُحدّدُ مفتاحَ لونِ الشفافيةَ لكي يُستَعملَ متى يَعدُّ النافذةَ ذات الطبقاتَ. كُلّ نقاط الشاشة تصَبغ بالنافذةِ بهذا اللونِ وسَيَكُونُ شفّاف. لتَوليد Colorref، يَستعملُ ماكرو RGB.
bAlpha
قيمة ألفا تُستَعملُ لوَصْف عدمِ شفافية النافذةِ ذات الطبقاتِ. مشابه لSourceConstantAlpha عضو تركيبِ Blendfunction. عندما تكون bAlphaقيمتها مساوية ل 0 ، النافذة شفّافةُ جداً. عندما تكون قيمة bAlpha مساوية 255، النافذة بليدةُ.
dwFlags
يُحدّدُ العمل الذي سوف يتَخْذ. هذا البارامترِ يُمكنُ أَنْ يَكُونَ واحد أَو أكثر مِنْ القِيَمِ التاليةِ.
LWA_COLORKEY
إستعمال crKey كلون الشفافيةَ.
LWA_ALPHA
إستعمال bAlpha لتَقْرير عدمِ شفافية النافذةِ ذات الطبقاتِ.
UpdateLayeredWindow:
Private Declare Function UpdateLayeredWindow Lib "user32" (ByVal hWnd As Long, ByVal hdcDst As Long, pptDst As Any, psize As Any, ByVal hdcSrc As Long, pptSrc As Any, crKey As Long, ByVal pblend As Long, ByVal dwFlags As Long) As Long
hwnd
مناولة إلى النافذةِ ذات الطبقاتِ. أي صفّفَ النافذةَ المَخْلُوقةُ بتَحديد WS_EX_LAYERED متى َخْلقُ النافذةَ بدالة CreateWindowEx أَو بوضع WS_EX_LAYERED عن طريق SetWindowLong بعد خُلِق النافذةِ
.hdcDst
مناولة إلى سياق أداةِ (دي سي) للشاشةِ. هذه المناولة تحصل عندما تستدْعى الدالة وتكون قيمتها محددة ب Null. هو يستعمل لتطابق لونِ لوحة الألوانِ عندما تحدث محتويات النافذةَ . إذا كانت قيمة hdcDst مساوية ل NULL، سوف تكون لوحة الألوان الأصلية مستعملة.
إذا كانت hdcSrc قيمتها Null , يَجِبُ أَنْ يَكُونَ hdcDstقيمتها Null.
pptDst
مؤشر إلى تركيب النقطةِ الذي يُحدّدُ موقعَ الشاشةِ الجديدِ للنافذةِ ذات الطبقاتِ. إذا كان الموقعِ الحاليِ غير متغيّرُ , يُمكنُ أَنْ يَكُونَ قيمة pptDst مساوية ل Null..
psize
[في] مؤشر إلى a تركيب حجمِ الذي يُحدّدُ الحجمَ الجديدَ للنافذةِ ذات الطبقاتِ. إذا حجمِ النافذةِ لا يَتغيّرُ , psize يُمكنُ أَنْ يَكُونَ ملغيَ. إذا hdcSrc ملغيُ , psize يَجِبُ أَنْ يَكُونَ ملغيَ.
hdcSrc
المناولة إلى دي سي للسطحِ الذي يُعرّفُ النافذةَ ذات الطبقاتَ. هذه المناولة يُمْكِنُ أَنْ يُحْصَلَ عليه بدَعوة دالة CreateCompatibleDC. إذا لم يتغيير الشكلِ والسياقِ البصريِ مِنْ النافذةِ ,فيُمكنُ أَنْ يَكُونَ قيمة hdcSrcَ مساوية ل Null .
pptSrc
مؤشر إلى تركيب النقطةِ الذي يُحدّدُ موقعَ الطبقةِ في سياقِ الأداةَ. إذا كانت قيمة hdcSrc مساوية ل Null ,فيَجِبُ أَنْ تَكُونَ قيمة pptSrc مساوية ل Null.
crKey
تركيب Colorref الذي يُحدّدُ مفتاحَ لونِ الشفافيةَ لكي يُستَعملَ متى يَعدُّ النافذةَ ذات الطبقاتَ. كُلّ نقاط الشاشة تصَبغ بالنافذةِ بهذا اللونِ وسَيَكُونُ شفّاف. لتَوليد Colorref، يَستعملُ ماكرو RGB.
pblend
مؤشر إلى تركيب Blendfunction الذي يُحدّدُ قيمةَ الشفافيةَ لكي يُستَعملَ متى يَعدُّ النافذةَ ذات الطبقاتَ.
dwFlags
هذا المتغيير يُمكنُ أَنْ يَكُونَ أحد القِيَمِ التاليةِ.
ULW_ALPHA
إستعمال pblend كدالة للمزيجَ. إذا كان نمطِ العرضَ 256 لونُ أَو أقل، تأثير هذه القيمةِ تماماً مثل تأثير ULW_OPAQUE
ULW_COLORKEY
إستعمال crKey كلون الشفافيةَ.
ULW_OPAQUE
إسحبْ نافذةَ ذات طبقاتَ بليدةَ.
إذا كانت قيمة hdcSrc مساوية ل Null , فأَنْ قيمة dwFlags يَجِبُ أن تكون صفر
GetWindowLong : هي الدالة المستخدمة لأسترجاع المعلومات المتعلقة بالويندوز المحدد، وتكون القيم للمعلومات المسترجعة من قبل هذه الدالة 32-bit وأذا أردت أسترجاع القيم 64-bit فيجب أستخدام الدالة GetWindowLongPtr .
Private Declare Function GetWindowLong Lib "user32" Alias "GetWindowLongA" (ByVal hWnd As Long, ByVal nIndex As Long) As Long
hwnd : معالجْ أو المناولة إلى النافذةِ، وبشكل غير مباشر، صنف class للنافذة التي تَعُودُ.
nIndex : ُحدّدُ المرجع أي نقطة الصفر إلى القيمةِ الّتي سَتُستَرجعُ. القِيَم الممكنة تكون في المدى صفر الى عددِ بايتاتِ ذاكرةِ النافذةِ الإضافيةِ، ناقص أربعة؛ على سبيل المثال، إذا حدّدتَ 12 أَو بايتاتَ أكثرَ مِنْ الذاكرةِ الإضافيةِ , 8 سَتَكُونُ قيمة دليل 32-bit الثالثِ من العدد الصحيح. لإسْتِرْجاع أيّ قيمة أخرى، يُحدّدُ القِيَمِة التاليةِ.
GWL_EXSTYLE التي تمثل أسترجاع أساليب الويندوز الممتدة.
SetWindowLong : الحالة التي تُغيّرُ خاصيّةَ النافذةِ المحدّدةِ.
Private Declare Function SetWindowLong Lib "user32" Alias "SetWindowLongA" (ByVal hWnd As Long, ByVal nIndex As Long, ByVal dwNewLong As Long) As Long
dwNewLong : يُحدّدُ قيمةَ البديلَ.
الكود بصورة كاملة – أطبع هذا الكود غي modTransparant
Option Explicit
'Transparancy API's
Private Declare Function SetLayeredWindowAttributes Lib "user32" (ByVal hWnd As Long, ByVal crKey As Long, ByVal bAlpha As Byte, ByVal dwFlags As Long) As Long
Private Declare Function UpdateLayeredWindow Lib "user32" (ByVal hWnd As Long, ByVal hdcDst As Long, pptDst As Any, psize As Any, ByVal hdcSrc As Long, pptSrc As Any, crKey As Long, ByVal pblend As Long, ByVal dwFlags As Long) As Long
Private Declare Function GetWindowLong Lib "user32" Alias "GetWindowLongA" (ByVal hWnd As Long, ByVal nIndex As Long) As Long
Private Declare Function SetWindowLong Lib "user32" Alias "SetWindowLongA" (ByVal hWnd As Long, ByVal nIndex As Long, ByVal dwNewLong As Long) As Long
Private Const GWL_EXSTYLE = (-20)
Private Const LWA_COLORKEY = &H1
Private Const LWA_ALPHA = &H2
Private Const ULW_COLORKEY = &H1
Private Const ULW_ALPHA = &H2
Private Const ULW_OPAQUE = &H4
Private Const WS_EX_LAYERED = &H80000
Public Function isTransparent(ByVal hWnd As Long) As Boolean
On Error Resume Next
Dim Msg As Long
Msg = GetWindowLong(hWnd, GWL_EXSTYLE)
If (Msg And WS_EX_LAYERED) = WS_EX_LAYERED Then
isTransparent = True
Else
isTransparent = False
End If
If Err Then
isTransparent = False
End If
End Function
Public Function MakeTransparent(ByVal hWnd As Long, ByVal Perc As Integer) As Long
Dim Msg As Long
On Error Resume Next
Perc = ((100 - Perc) / 100) * 255
If Perc < 0 Or Perc > 255 Then
MakeTransparent = 1
Else
Msg = GetWindowLong(hWnd, GWL_EXSTYLE)
Msg = Msg Or WS_EX_LAYERED
SetWindowLong hWnd, GWL_EXSTYLE, Msg
SetLayeredWindowAttributes hWnd, 0, Perc, LWA_ALPHA
MakeTransparent = 0
End If
If Err Then
MakeTransparent = 2
End If
End Function
Public Function MakeOpaque(ByVal hWnd As Long) As Long
Dim Msg As Long
On Error Resume Next
Msg = GetWindowLong(hWnd, GWL_EXSTYLE)
Msg = Msg And Not WS_EX_LAYERED
SetWindowLong hWnd, GWL_EXSTYLE, Msg
SetLayeredWindowAttributes hWnd, 0, 0, LWA_ALPHA
MakeOpaque = 0
If Err Then
MakeOpaque = 2
End If
End Function
الكود في ال frmMain
Option Explicit
Private Sub scrTransparancy_Change()
modTransparant.MakeTransparent Me.hWnd, scrTransparancy.Value
lblStatus.Caption = CStr(scrTransparancy.Value) & "% transparancy"
End Sub
******************************************* B) ************************ :o ***************************** :wacko: ************
ألجزء الثانى:-
سأتواصل بشرح بعض دوال API أخرى من خلال توضيح المثال أدناه:
المثال الثاني: كيف نضيفُ ProgressBar إلى StatusBar
سأشرح في هذا المثال ثلاث دوال
يتكون الفورم من عنصريين StatusBar1 و ProgressBar1
الدالة SetParent : الدالة تستخدم لتُغيّرُ النافذةَ الأصلَ لنافذةِ الطفلِ المحدّدةِ.
Private Declare Function SetParent Lib "user32" (ByVal hWndChild As Long, ByVal hWndNewParent As Long) As Long
hWndChild
المناولة إلى نافذةِ الطفلَ.
hWndNewParent
المناولة إلى النافذةِ الأصلِ الجديدةِ. إذا كانت قيمة هذا المتغيير ، ستُصبحُ نافذةَ سطح المكتبَ هي النافذةَ الأصلَ الجديدةَ. الويندوز 2000 / إكس بي: إذا كان هذا المتغيير HWND_MESSAGE ، ستُصبحُ نافذة الطفلَ نافذة رسالة فقط .
الدالة SendMessage : تُرسلُ الدالة الرسالةَ المحدّدةَ إلى نافذة أَو عدة نوافذ. يَدْعو إجراءَ النافذةَ للنافذةِ المحدّدةِ ولا يَعُودُ حتى يتم تنفيذ الرسالةَ من قبل البرنامج الفرعي.
Private Declare Function SendMessageAny Lib "user32" Alias "SendMessageA" (ByVal hwnd As Long, ByVal msg As Long, ByVal wParam As Long, lParam As Any) As Long
hWnd
المناولة إلى النافذةِ التي إجراءِ نافذتِها سَتَستلمُ الرسالةَ. إذا كان هذا المتغييرِ إتش دبليو إن دي _ إرسال، الرسالة تُرسَلُ إلى كُلّ النوافذ العالية المستوى في النظامِ، بضمن ذلك النوافذِ المخفيةِ أَو المُعوّقةِ، النوافذَ المتداخلة، والنوافذ البارزة؛ ولكن الرسالةَ لَن تُرسَلْ إلى نوافذِ الطفلِ.
Msg
يُحدّدُ الرسالةَ لكي تُرسَلَ.
wParam
يُحدّدُ معلوماتَ الرسالةً الإضافيةً المعيّنةَ.
lParam
يُحدّدُ معلوماتَ الرسالةً الإضافيةً المعيّنةَ.
الدالة تُغيّرُ الموقعَ وأبعادَ النافذةِ المحدّدةِ. لنافذة عالية المستوى، الموقع والأبعاد تكون نسبة إلى الزاوية العليا اليسرى مِنْ الشاشةِ.أما نافذة الطفلِ، تكون نسبة إلى الزاوية العليا اليسرى مِنْ النافذةِ الأصلِ.
hWnd
المناولة إلى النافذةِ.
X
يُحدّدُ الموقعَ الجديدَ للجانبِ اليسارِ للنافذةِ.
Y
يُحدّدُ الموقعَ الجديدَ لقمةِ النافذةِ.
nWidth
يُحدّدُ العرضَ الجديدَ للنافذةِ.
nHeight
يُحدّدُ الإرتفاعَ الجديدَ للنافذةِ.
bRepaint
يُحدّدُ سواء سَتُصْبَغُ النافذةَ ثانية. إذا كانت قيمة هذا المتغييرِ حقيقيُ، النافذة تَستلمُ رسالة. أما إذا كانت القيمةِ خاطئُ، لا تحدث أي عملية صِباغَة ثانية . هذا يطبق على منطقةِ الزبونَ، منطقة غير زبون (تتضمن حانةِ العنوانَ وحاناتَscrollBar )، وكَشفَ أيّ جزء لنافذةِ الأصلِ كنتيجة لإنتقال نافذة الطفلِ.
Private Declare Function SetParent Lib "user32" (ByVal hWndChild As Long, ByVal hWndNewParent As Long) As Long
Private Declare Function SendMessageAny Lib "user32" Alias "SendMessageA" (ByVal hwnd As Long, ByVal msg As Long, ByVal wParam As Long, lParam As Any) As Long
Private Declare Function MoveWindow Lib "user32" (ByVal hwnd As Long, ByVal x As Long, ByVal y As Long, ByVal nWidth As Long, ByVal nHeight As Long, ByVal bRepaint As Long) As Long
Private Type RECT
Left As Long
Top As Long
Right As Long
Bottom As Long
End Type
Private Const WM_USER As Long = &H400
Private Const SB_GETRECT As Long = (WM_USER + 10)
Public Sub SetProgressBarToStatusBar(ByVal hWnd_PBar As Long, ByVal hWnd_SBar As Long, ByVal nPanel As Long)
Dim R As RECT
SendMessageAny hWnd_SBar, SB_GETRECT, nPanel - 1, R
SetParent hWnd_PBar, hWnd_SBar
MoveWindow hWnd_PBar, R.Left, R.Top, R.Right - R.Left, R.Bottom - R.Top, True
End Sub
Private Sub Form_Load()
SetProgressBarToStatusBar ProgressBar1.hwnd, StatusBar1.hwnd, 2
End Sub
