The documentation for library libGUI.
Controls.
libGUI is library of GUI components for operational system KolibriOS.
GUI the component consists of two elements - structure Control containing the information about GUI a component, and обработчика контрола. That is functions which draws GUI a component and are defined(determined) with his(its) behaviour depending on conditions: mice, keyboards and messages received from the program.
Control is structure with the general(common) heading in 44 байта. There are fields specific to the given type GUI of a component further. What fields it will be - the programmer writing обработчик GUI of a component defines(determines). Also variables which can contain any data necessary for work обработчика a component can be stored(kept) in the control.
The general(common) heading of control consists of the following fields:
struc CONTROL
{
.ctrl_proc rd 1
.ctrl_fd rd 1
.ctrl_bk rd 1
.child_fd rd 1
.child_bk rd 1
.parend rd 1
.ctrl_x rd 1
.ctrl_y rd 1
.ctrl_sizex rd 1
.ctrl_sizey rd 1
.ctrl_ID rd 1
}
ctrl_proc Is a field contains обработчика address for GUI a component. Fields: ctrl_fd, ctrl_bk, child_fd, child_bk, lists are necessary for the organization контролов in two-messengers. controls can be organized as a tree from lists, approximately just as it occurs to catalogues. These fields are used only by library libGUI therefore them it is impossible to use (in them impossible to write).
parend is a field contains the index on контрол which is the parent for given контрола. If to lead(carry out) analogy to catalogues parend is a root catalogue. And all affiliated elements parend-and are subdirectories in the root catalogue. parend specifies area of memory in the size in 44 байта (the size of structure control). At initialization of the program this area of memory is necessary for nulling (simply it is possible to create a file filled in zero), that невозникло mistakes in work of library.
ctrl_x Is x coordinate контрола, counted from the top left corner клиентской areas of a window. For пермещения контрола inside онка it is necessary to change contents of coordinate x in this field.
ctrl_y Is y coordinate контрола, counted from the top left corner клиентской areas of a window. For пермещения контрола inside a window it is necessary to change contents of coordinate y in this field.
ctrl_sizex - size GUI of a component on an axis x.
ctrl_sizey - size GUI of a component on an axis y.
ctrl_ID - the identifier контрола. This parameter is set by library and it(he) cannot be changed (it is impossible to write in this field).
For creation GUI of a component in libGUI the functions having the name crate_название_контрола are used. So, that are these functions of creation контрола.
In libGUI the standard according to which, all parameters with котролами are transferred functions of work through a stack is accepted. The function creating контрол, two parameters (are transferred by way of their entering in a stack): the index on parend-and, the index on structure with the data for given GUI a component. That it will be for the data - the programmer writing the given component decides. But these data necessarily should contain information on coordinates and the size контрола.
After through a stack indexes on the necessary data are transferred(handed), it is necessary to create контрол. For this purpose in libGUI there is a function crate_control. For acceleration of work of library, parameters for this function are transferred through registers. The register eax contains quantity(amount) of byte which it is necessary to reserve under structure control. Рассчёт to be made under the formula: 44 + quantity(amount) of byte for data GUI of a component. In the register ebx transfers the index to the parent. After a call crate_control in the register eax transfers the index to structure control with filled system (for library) fields. Now it is necessary to bring the information in контрол. On the appropriate displacement described above, it is necessary to write down: the index on обработчика address given GUI a component, coordinate of a component, the size of a component. And also it is necessary to copy the data specific to the given component, to the address указатель_на_контрол+44. That is all data necessary for work will be stored(kept) for system (behind heading control). After end of these actions, function of creation of a component should transfer through a stack the index on created контрол with the filled fields.
For transfer of the information контролам, in library the system of messages is used. The message is the index on area of memory in the size of 16 bytes.
The first 4 байта are reserved under type of the message. In total it is possible 5 types of messages: the message on full copying (a code 1), the message from the keyboard (a code 2), the specialized message (a code 3), the message from the mouse (a code 6), the message on removal(distance) контрола (a code-1).
The specialized message is necessary when it is necessary to draw again separate контрол at any moment of time (for example a strip of progress in ProgressBar-е) .Или for other situations (for example for switching-off контрола).
The following 4 байта in the message depend on type of the message. If there was a message 1 the following байты for work are not required. If there was a message 2 the subsequent 4 байта is a code of the pressed key (scan a code or ascii a code). In the message 3 subsequent байты too are not necessary. For the message 6 subsequent values are coordinates x and y mice, and also conditions of buttons the mice received from function 37 under functions 2.
Messages controls receive from the program. For message transfer from the program to контролам, in library there is a function send_message. As parameters to it(her) transfers the index to the parent for контролов and the index on the message. This function dispatches messages контролам, being affiliated for the given parent (dispatch of the message represents a call обработчика контрола with transfer to it(him) messages through a stack). In turn, if affiliated controls are parents for any others контролов обработчики affiliated контролов, dispatch messages affiliated контролам.
Messages from the keyboard, are accessible not to all контролам, but only active. Контрол it is considered active if index of the mouse to be above it(him) and if on it(him) click of the mouse was made. Thus, if you type(collect) the text in one of EditBox-ов messages from the keyboard this GUI will receive a component, instead of any another.
For removal(distance) контрола in libGUI there is a function destroy_control. This function deletes контрол from the list affiliated контролов that parent (parend-and) to which belongs and liberates memory from under контрола. As parameter of this function transfers the index on контрол (that index which is returned with function crate_название_контрола). At removal(distance) контрола, обработчику контрола the message with a code-1 is sent. If at контрола is affiliated controls обработчик контрола dispatches them the message with a code-1. If at контрола is not present affiliated контролов there is simply a returning from обработчика контрола.
Button is a button. For creation of this component function crate_button is used. We shall consider, what parameters are necessary for transferring this function for creation of the button. The structure with the data for the button looks like:
struc BUTTON
{
. type db 1
. flag db 1
. x dw 1
. y dw 1
. width dw 1
. height dw 1
. image dd 1
. imageX dw 1
. imageY dw 1
. imageSizeX dw 1
. imageSizeY dw 1
. transparentColor dd 1
. text dd 1
. textX dw 1
. textY dw 1
. textcolor dd 1
. color1 dd 1
. color2 dd 1
. mouseX dw 1
. mouseY dw 1
}
The field type defines(determines) type of the button and sets some parameters of initialization.
Installation of the grown-up a bat (7-th) resolves full copying the button. Establish this of bats in 1 at initialization of the button.
Installation the fourth bat defines(determines) appearance of the button. If bats it is established in 1 the volumetric button with градиентными заливками will be drawn. The flat button otherwise will be drawn.
At installation zero the bat is drawn the button with the text. The text is automatically aligned(centred) on the button. For drawing the button with the text it is necessary to bring in a field text the index for a line with the text (the line necessarily should come to an end in zero). And in a field textcolor - color of the text.
Installation the first bat sets the button with a picture. The picture is automatically aligned(centred) on the button. For drawing a picture on the button it is necessary to bring in a field image the index on a picture. Also it is necessary to set the size of a picture in fields imageSizeX and imageSizeY. And one more additional параметер - color of a transparency for картики transparentColor.
The second bats it is responsible(crucial) for a simultaneous conclusion of a picture and the text to the button. In this case it is necessary to set coordinates of the text and coordinate of a picture on the button. Coordinates are set from the left top corner of the button. textX and textY set coordinates of the text, and imageX and imageY coordinates of a picture.
The third bats drawing the button, but the button всёравно disconnects exists and reacts to prompting and pressing машью. If to establish this of bats together with bats: 0, either 1, or 2 всёравно will be drawn the text, a picture, or that and another together. This useful property can be used for creation of other components.
The field color1 sets colors of a component (on the basis of him(it) other colors are generated). This color is the best way for taking from the standard table of colors which is loaded by 48 system function KolibriOS. And then it is necessary to take the third color from this table (displacement 8).
In fields x and y coordinates of the button are set. In a field width width of the button (the size on an axis x), in a field height height of the button (the size on y).
Other fields of structure are used for a data storage контрола in an operating time.
The data on a condition of the button enter the name in a field flag контрола. It is necessary to remember, that the data in all контролах begin after heading контрола, length 44 байта. That is for the button the field flag will have displacement 45 concerning the beginning контрола. If in this field it is established 0-th bats, the cursor of the mouse means to be above the button. If it is established 0-th and 1-st bats, the cursor means to be above the button and the button is pressed. Using this information in the program, it is possible to make, that there was a reaction to pressing or отпускание buttons.
Scroler is a strip of scrolling. This component creates function crate_scroler. As parameter it is necessary for it(him) to transfer the following structure:
struc SCROLER
{
. type rb 1
. x rw 1
. y rw 1
. length rw 1
. color1 rd 1
. size rd 1
. pos rd 1
. mouseX rw 1
. mouseY rw 1
. buttons_flags rw 1
. ChildButtton1 rd 1
. ChildButtton2 rd 1
}
Fields: x, y, color1 have the same sense, as in GUI component Button (is (see higher).
The field type sets type скролера. Bats 7 and 4 carry out the same role, as for buttons. Bats 6 and 5 need to be established in 1 at initialization скролера. At installation 0-th bat is drawn vertical скролер and if it is established 1-st bats horizontal.
The field length sets length скролера in пикселах. On edges(territories) скролера there are buttons. Each of them has the size 16x16 пикселов. Minimally possible(probable) size of a toddler - 4 пиксела. Therefore the minimal size скролера 36 пикселей.
The field size sets the size of a toddler скролера. This size material also varies from 0 up to 1. To zero there corresponds(meets) the minimal size of a toddler (4 пиксела), and 1 - maximal (from one button up to another).
The field pos sets a position of a toddler on scroler-е. This size too material also varies from 0 up to 1. If to write down in this field value a toddler to be established in the appropriate position. And if to move a toddler the mouse contents of this field will vary depending on position of a toddler.
In a field buttons_flags храняться conditions of buttons of the mouse. The first button of the mouse considers what is the closest to a point with coordinates (x, y) (to a point in which it is drawn скролер). If it is established zero bats in this field then the first button and if 4-th bats the second is pressed.
Fields: ChildButton1, ChildButton2 store(keep) контролов addresses of affiliated buttons скролера. These fields are used обработчиком скролера and they cannot be changed.
For work with скролером, it is necessary to read / write from / in fields size or pos. Addresses (displacement) of the appropriate fields контрола are equal: 44 + displacement in a field of structure.
Component Zakladka is necessary when it is necessary to work with a plenty various контролов. For creation of a bookmark in library function crate_zakladka is used. As bookmarks can be much and they can meet in different configurations the structure with the data for a bookmark, has variable length. But the first a little bit(some) fields of a bookmark - are standard. We shall disassemble all over again these fields.
struc ZAKLADKA
{
. type rb 1
. flag rb 1
. x rd 1
. y rd 1
. sizex rd 1
. sizey rd 1
. color_1 rd 1
. reserved rd 1
. color2 rd 1
.......................
}
To initialize a bookmark in a field type it is necessary to establish 7-th bats. More any битов in this field to establish it is not necessary.
Sense of fields: x, y, sizex, sizey, it be clear intuitively.
The field color_1 sets color of a bookmark. And a field color2 color of the text on a bookmark.
Further in a bookmark fields of variable length begin. Each field on 4 байта. The first goes a field containing the general(common) number of lines of bookmarks. The line is understood as a number(line) from bookmarks. There is a field containing total of bookmarks in the first line, then a field containing quantity(amount) of bookmarks in the second line, and so up to a field with the information on the latest line further. We shall consider an example. Let we have bookmark with three lines. In the first line of 3 bookmarks, in the second 2, and in the third 1. Then the column (a field of structure) from 4 byte numbers will look so:
|
3 |
|
3 |
|
2 |
|
1 |
Further there is consistently one after another an information on each bookmark. Bookmarks are listed(transferred) with is left on the right, from above in a bottom. That is the first bookmark will be the bookmark of the top lines which is taking place at a left edge, and last a bookmark of the bottom lines taking place at a right edge.
The information on each bookmark has variable length (depends on number контролов on a bookmark) and in a general view looks so:
The index on the text for n-ой bookmarks
Quantity(amount) контролов on n-ой to a bookmark
Type of 1-st контрола on n-ой to a bookmark
The index on structure with the data for 1-st контрола on n-ой to a bookmark
....................................... ................................................................
....................................... ................................................................
Type of the last контрола on n-ой to a bookmark
The index on structure with the data for the last контрола on n-ой to a bookmark
The type контрола is defined(determined) by his(its) serial number in library libGUI. For the button this number 1, for скролера - 2 etc.
After you have transferred function crate_zakladka structure with the data, this function creates controls for bookmarks. These controls are affiliated for a bookmark. Indexes on controls will be worn out in fields where there were indexes on the data for affiliated контролов earlier. That is now in a field:
The index on structure with the data for k-го контрола on n-ой to a bookmark
There will be an index on created контрол with the appropriate type. And to write / read the data from affiliated контролов it is necessary to receive the index on this контрол. For this purpose it is necessary to take the index on контрол bookmarks to add 44 + displacement of the appropriate field in structure with the data (for the best understanding look the examples applied to library). After the index on affiliated контрол is received, extraction of the information from him(it) needs to be made according to type of it контрола.
image is a component for work with images. For creation контрола this type in libGUI function crate_image is used. The structure with the data for this function looks like:
struc IMAGE
{
. type rb 1
. flag rb 1
. color rd 1
. x rd 1
. y rd 1
. sizex rd 1
. sizey rd 1
. pointer rd 1
}
By default in a field type anything to establish it is not necessary. But, if you want, that this контрол reacted to the specialized messages it is necessary to establish 0-th bats. After reception of the specialized message контрол перерисовывается also dumps(resets) 0 bats. That is each time before a parcel(sending) of the specialized message needs to be established 0-th bats. This of bats serves as a trap for the specialized messages.
Fields x and y set coordinates of a picture. sizex, sizey the size of a picture.
pointer - the index on area of memory where to be картика in format RRGGBB (3 байта on пиксель). Other fields зарезервированы for work обработчика given контрола.
If you want, that the component reacted to the specialized messages, establish 0-th bats to the address (concerning the beginning контрола) 44 + displacement of a field type.
text is a component for work with the text. For creation of this component function crate_text is used. The structure with the data for this function looks like:
struc TEXT
{
. type rb 1
. flag rb 1
. color rd 1
. x rd 1
. y rd 1
. length rd 1
. pointer rd 1
}
By default in a field type any битов to establish it is not necessary. But if you want, that контрол each time before a parcel(sending) of the specialized message reacted to the specialized messages it is necessary to establish 2-nd bats. Installation of it a bat includes a trap for the specialized messages. After reception of the specialized message of 2-nd bats it is dumped(reset). Also in this control there is an opportunity to disconnect from рисовку the text. It is necessary for for this purpose will establish 0-th bats. This opportunity can be useful, if you use variable number affiliated контролов in such контролах as Zakladka where dynamically it is impossible to change number affiliated контролов (all affiliated controls are created once - at initialization of a component).
In a field pointer to be brought the index on the text, and in a field length length of the text (in symbols).
If you want, that the component reacted to the specialized messages, establish 2-nd bats to the address (concerning the beginning контрола) 44 + displacement of a field type. And if want, that контрол not отрисовывался establish 0-th bats to the same address.
Component Number is a component for a conclusion of numbers (as the whole, and material). This component creates by means of function crate_number. The structure with the data for this purpose контрола looks like:
struc NUMBER
{
.type rb 1
.flag rb 1
.color rd 1
.x rd 1
.y rd 1
.number rd 1
.parameters rd 1
}
Let's consider a field type. Installation 0-th bat in this field forbids drawing контрола. 1-й bats it is responsible(crucial) for type of number. If this of bats is not established, the integer and if it is established number from a "floating" point will be deduced(removed). Installation 2-nd bat includes a trap for the specialized messages. After reception of the specialized message of 2-nd bats it is dumped(reset).
Fields x and y set coordinates of a component. color - defines(determines) color of number. In a field number the number which is required to deduce(remove) (the whole or material) enters the name.
The field parameters defines(determines) a format of deduced(removed) number. If to be deduced(removed) an integer grown-ups of 16 bats of this number set quantity(amount) of marks for a conclusion of number. If to be deduced(removed) number from a floating point grown-ups of 16 bats set number of marks of the whole part of material number, and younger 16 bats number of marks after a point. Remember, that the maximal size of material number is limited to 32 bats.
If you want, that the component reacted to the specialized messages, establish 2-nd bats to the address (concerning the beginning контрола) 44 + displacement of a field type. And if want, that контрол not отрисовывался establish 0-th bats to the same address.
CheckBox is a component for a choice of options. It(he) allows to include or switch off action of any option. This component creates function crate_check_box. As parameter of this function the following structure transfers:
struc CHECKBOX
{
. ch_flags rw 1
. ch_left rw 1
. ch_top rw 1
. ch_text_margin rd 1
. ch_size rd 1
. ch_size_2 rw 1
. ch_size_3 rw 1
. ch_color rd 1
. ch_border_color rd 1
. ch_text_color rd 1
. ch_text_pt rd 1
. ch_text_length rw 1
. mouseX rd 1
. mouseY rd 1
}
Let's consider a field ch_flags. If in this field 0 it is drawn inactive CheckBox. And if to establish 1-st bats, active.
ch_left - coordinate of a component on an axis x.
ch_top - coordinate of a component the size on an axis y.
ch_size - the size of a component (it(he) square).
ch_color - color of an internal part of a component.
сh_border_color - color of a framework of a component.
ch_text_color - color of the text.
ch_text_ptr - the index on the text for CheckBox-and.
ch_text_length - length of the text (in symbols).
Work with GUI component CheckBox.
For data acquisition about condition CheckBox - and, it is necessary to read his(its) condition from a field flags. and on a condition described above битов to check a condition of a component. In котроле this field to be on displacement (concerning the beginning контрола) 44 + displacement of a field flags in structure.
EditBox is a component for вввода: тектса, numbers. This component creates function crate_edit_box. As parameter of this function the following structure transfers:
struc EDITBOX
{
. ed_width rd 1
. ed_left rd 1
. ed_top rd 1
. ed_color rd 1
. ed_focus_border_color rd 1
. ed_blur_border_color rd 1
. ed_text_color rd 1
. ed_max rd 1
. ed_text rd 1
. ed_flags rw 1
. ed_size rd 1
. ed_pos rd 1
. ed_offset rd 1
. cl_curs_x rd 1
. cl_curs_y rd 1
. ed_shift_pos rd 1
. ed_shift_pos_old rd 1
. ed_height r rd 1
. mouseX rd 1
. mouseY rd 1
}
Let's consider a field........
.............
For data acquisition entered in EditBox-е it is necessary.......
.............