10
« on: March 21, 2023, 10:47:08 am »
The EZGUI docs don't go into detail about creating and using components. This post is where I will try to explain it better. I will give an brief overview and then over time add more to this discussion.
What is a component ?
A component is like a page form (which can be put on a normal form) which acts like a single control. You can put any child controls on the component and make it do some repeatable task, but to your app it will act like a single control.
You can create a component once and use it over and over again on different forms.
You do not create a component like you do a normal form, even though technically it is a form with child controls. There are special commands for defining a component and even processing its events and also sending events from the component to your app (remember it appears to your app as a single complex custom control).
The designer needs a component to be compiled to a DLL so you can use it there when visually designing your app. But a component in your app can be accessed either in its compiled form (DLL) or as source code (designer will generate the path to the source code if you desire rather than load a DLL when it generates your source code).
Components are a bit complex at first glance and is an advanced feature. But once you start learning how to use them it really is not that difficult.
Let's look at some source code for a component that comes with EZGUI (Canvas Scroller):
' ======================================
' [PROTECTED CODE] Do NOT Edit !
' ======================================
DECLARE SUB EZ_CSCROLLER_InitComponent(BYVAL CMPPrefix$)
DECLARE SUB EZ_CSCROLLER_Design()
DECLARE SUB EZ_CSCROLLER_ParseEvents(CID&, CMsg&, CVal&, Cancel&)
DECLARE SUB CSCROLLER_Events(CID&, CMsg&, CVal&, Cancel&)
' ------------------------------------------------
%CSCROLLER_MYPICTURE = 100
'<<BEGINFORM>> "CSCROLLER"
' ======================================
' [PROTECTED CODE] Do NOT Edit !
' ======================================
SUB EZ_CSCROLLER_InitComponent(BYVAL CMPPrefix$) ' (PROTECTED)
EZ_DefComponent CMPPrefix$+"CSCROLLER", "SVBK||CSCROLLER.bas", CODEPTR(EZ_CSCROLLER_Design), CODEPTR(EZ_CSCROLLER_ParseEvents)
END SUB
SUB EZ_CSCROLLER_Design() ' (PROTECTED)
LOCAL CText$
EZ_Color-1,-1
EZ_UseFont 4
EZ_UseAutoSize "CT"
EZ_Picture %CSCROLLER_MYPICTURE, 0, 0, 6, 3, "SAMPLEBMP", ""
' -----------------------------------------------
END SUB
SUB EZ_CSCROLLER_ParseEvents(CID&, CMsg&, CVal&, Cancel&) ' (PROTECTED)
SELECT CASE CID&
CASE %EZ_Window
CSCROLLER_Events CID&, CMsg&, CVal&, Cancel&
CASE ELSE
CSCROLLER_Events CID&, CMsg&, CVal&, Cancel&
END SELECT
END SUB
' ======================================
' [USER ACCESSABLE CODE] You may Edit !
' ======================================
'<<SAVE>>
SUB CS_ShowPicture(BYVAL P$)
LOCAL W&, H&, CW&, CH&, FW!, FH!, SW&, SH&, SF$, X&, Y&, XDif&, YDif&, VScroll&, HScroll&, EW&, EH&
EZ_HideC "{ME}",%CSCROLLER_MYPICTURE,%CSCROLLER_MYPICTURE
IF P$="" THEN
EZ_HideFormScrollBars "{ME}", "B"
EXIT SUB
END IF
IF EZ_ImageHandle(P$)<>0 THEN
EZ_GetPictureSize P$, W&, H&
EZ_HideFormScrollBars "{ME}", "B"
EZ_GetSize "{ME}",FW!, FH!, 2
VScroll&=0
HScroll&=0
CW&=FW!
CH&=FH!
SW&=EZ_WO("SW")
SH&=EZ_WO("SH")
SF$=""
IF W&<=CW& AND H&<=CH& THEN
' no scrollbars
X&=(CW&-W&)\2
Y&=(CH&-H&)\2
ELSE
EW&=0
EH&=0
IF W&>CW& THEN EH&=SH&
IF H&>CH& THEN EW&=SW&
IF W&>(CW&-EW&) THEN
X&=0
SF$=SF$+"H"
HScroll&=W&-(CW&-EW&)
ELSE
X&=((CW&-EW&)-W&)/2
END IF
IF H&>(CH&-EH&) THEN
Y&=0
SF$=SF$+"V"
VScroll&=H&-(CH&-EH&)
ELSE
Y&=((CH&-EH&)-H&)/2
END IF
END IF
IF X&<0 THEN X&=0
IF Y&<0 THEN Y&=0
EZ_ResizeC "{ME}",%CSCROLLER_MYPICTURE, EZ_CX(X&),EZ_CY(Y&), EZ_CX(W&),EZ_CY(H&)
EZ_SetImage "{ME}",%CSCROLLER_MYPICTURE, P$
EZ_ShowFormScrollBars "{ME}", SF$
EZ_ShowC "{ME}",%CSCROLLER_MYPICTURE,%CSCROLLER_MYPICTURE
IF INSTR(SF$,"H") THEN
' EZ_SetHScroll "{ME}",0, 0, HScroll&, 0,(HScroll&\10)+1
EZ_SetHScroll "{ME}",0, 0, HScroll&, 0,1
END IF
IF INSTR(SF$,"V") THEN
' EZ_SetVScroll "{ME}",0, 0, VScroll&, 0,(VScroll&\10)+1
EZ_SetVScroll "{ME}",0, 0, VScroll&, 0,1
END IF
END IF
END SUB
SUB ScrollMe(BYVAL SMode&, BYVAL CVal&)
LOCAL C!, R!, W!, H!
EZ_GetSizeC "{ME}",%CSCROLLER_MYPICTURE,C!, R!, W!, H!
IF SMode&=-1 THEN
R!=0-EZ_CY(CVal&)
ELSE
C!=0-EZ_CX(CVal&)
END IF
EZ_ResizeC "{ME}",%CSCROLLER_MYPICTURE,C!, R!, W!, H!
END SUB
SUB FreeMyStartBitmap()
LOCAL P$
P$=EZ_GetCmpText("{ME}",0,1)
IF P$<>"" THEN
EZ_FreeImage P$
EZ_SetCmpText "{ME}",0,"", 1
END IF
END SUB
'<<END>>
SUB CSCROLLER_Events(CID&, CMsg&, CVal&, Cancel&)
LOCAL P$
SELECT CASE CID&
CASE %EZ_Window
SELECT CASE CMsg&
CASE %EZ_Loading
CASE %EZ_Loaded
EZ_HideFormScrollBars "{ME}", "B"
EZ_HideC "{ME}", %CSCROLLER_MYPICTURE, %CSCROLLER_MYPICTURE
P$=EZ_GetText("{ME}",0)
EZ_SetText "{ME}",0,""
IF P$<>"" THEN
IF UCASE$(RIGHT$(P$,4))=".BMP" THEN
P$=EZ_LoadPicture(P$)
IF P$<>"" THEN
CS_ShowPicture P$
EZ_SetCmpText "{ME}",0,P$,1
END IF
ELSE ' assume it is a Picture string
CS_ShowPicture P$
END IF
END IF
CASE %EZ_TextUpdated
SELECT CASE CVal&
CASE 1
CASE ELSE
END SELECT
CASE %EZ_BitmapUpdated
FreeMyStartBitmap
P$=EZ_GetBitmapName(CVal&)
CS_ShowPicture P$
CASE %EZ_ColorUpdated
LOCAL FG&, BG&
FG&=EZ_GetCmpAttr("{ME}",0,1)
BG&=CVal&
EZ_SetColor "{ME}",0, FG&, BG&
CASE %EZ_FontUpdated
CASE %EZ_SelUpdated
CASE %EZ_ClearUpdated
CS_ShowPicture ""
CASE %EZ_FreeNow
FreeMyStartBitmap
CASE %EZ_Started
CASE %EZ_Close
CASE ELSE
END SELECT
CASE -1 ' Vertical scrollbar
IF CMsg&=%EZ_Change THEN
ScrollMe -1, CVal&
END IF
CASE -2 ' Horizontal scrollbar
IF CMsg&=%EZ_Change THEN
ScrollMe -2, CVal&
END IF
CASE ELSE
END SELECT
END SUB
The designer generates a subroutine for adding the component to one of your forms:
SUB EZ_CSCROLLER_InitComponent(BYVAL CMPPrefix$)
In this routine is a call to EZ_DefComponent:
EZ_DefComponent CMPPrefix$+"CSCROLLER", "SVBK||CSCROLLER.bas", CODEPTR(EZ_CSCROLLER_Design), CODEPTR(EZ_CSCROLLER_ParseEvents)
What is not provided is a example of how to put your components into a DLL. You can put more than one component in a DLL to create a library of compoments. Once compiled to a DLL the DLL and the source code for the components should be put in the EZGUI Designers component folder.
Here is an example of a component DLL:
#COMPILE DLL "cmplib1.dll"
#INCLUDE "C:\ezgui45beta\includes\ezgui50.inc"
FUNCTION LIBMAIN (BYVAL hInst&, BYVAL FReason&, BYVAL lpR&) AS LONG
SELECT CASE FReason&
CASE 0 ' %DLL_PROCESS_DETACH
CASE 1 ' %DLL_PROCESS_ATTACH
CASE 2 ' %DLL_THREAD_ATTACH
CASE 3 ' %DLL_THREAD_DETACH
CASE ELSE
END SELECT
FUNCTION=1
END FUNCTION
#INCLUDE "C:\ezgui45beta\projects\real components\Form_pgscroller\pgscroller.bas" ' Component include file!
#INCLUDE "C:\ezgui45beta\projects\real components\Form_cscroller\cscroller.bas" ' Component include file!
SUB EZ_InitComponent(BYVAL CMPPrefix$) EXPORT
EZ_PGSCROLLER_InitComponent CMPPrefix$
EZ_CSCROLLER_InitComponent CMPPrefix$
END SUB
The two components that come with EZGUI are in separate files and must be included in this DLL code file and this is how I created the component DLL that comes with EZGUI.
A component needs an entrance function and that is predefined by EZGUI and always is:
SUB EZ_InitComponent(BYVAL CMPPrefix$) EXPORT
The function must be exported to EZGUI (and the designer) can find it the function. The function is found by polling the DLL for it by name and then it is called dnyamically (no Declare required).
Show Posts