{Form|_containing_controls}

CLASS {Form|_containing_controls} , UNTESTED, DESTRUCTORS :

A form class. It is intended to create your own descendants where a form components configuration is defined and methods are overridden to handle events from form components and from the form itself. In the visual components libray of the AL-IV, all the visual controls are placed on columns which are placed on a form. More complex nesting is not allowed, to exclude too complex configurations which can not fit into small displays.

---------------------------------------------------------- 'create / close'

STR Alias|_form

Form's alias (can be useful o distinct forms while switching in code via a CASE statement).

{Control} Child|ren|_controls[] , READ

The list of all the child controls (not columns, but all the controls on all the columns).

INT Handle|_native , READ

The form handle which is a descriptor to connect the AL-IV object of the form with its native implementation object.

{Screen} Screen_|object_ , INIT

The refernce to the {Screen} object which actually should be the single in an application instance.

---------------------------------------------------- 'native Window handle'

 

METHOD Window_handle ==> INT , DEPRECATED('Platform dependent')	Form's window handle. This is not the same as the descriptior of the native form's object but a platform-specific reference onto a window handle (in the Microsoft [TM] Windows system).
METHOD Show_application_button|_for_the_form (      BOOL Value|_show ) , DEPRECATED('Platform dependent')

--------------------------------------------------- 'form caption, borders'

METHOD Caption|_form ==> STR	Form caption string.
METHOD Set_caption ( STR V|alue_caption ) , SETTER FOR Caption	Changing the form caption string.

BOOL No_frame|_was_set , READ

Setting (or resetting) form "no frame" mode. This option is platform dependent and can be ignored.

BOOL No_borders , READ

Setting (or resetting) form "no borders" mode. This option is platform dependent and can be ignored.

BOOL Custom_colors , READ

Setting colors of form.

INT Custom_foreground|_color , READ

INT Custom_background|_color , READ

--------------------------------------------------------- 'position & size'

   

METHOD Bounds|_of_form_in_points ==> {rect}	Form bounds rectangle (on entire screen). In some cases (multi-monitor systems in Windows OS, e.g.) coordinates can be negative.
METHOD Set_bounds ( {rect} V|alue_new_bounds )
METHOD Left|_position_points ==> REAL	Form left coordinate (on entire screen). In some cases coordinates can be negative.
METHOD Set_left ( REAL L|eft_points ) , SETTER FOR Left	Setting the form left coordinate (on entire screen).
METHOD Top|_position_points ==> REAL	Form top coordinate. In some cases coordinates can be negative.
METHOD Set_top|_position ( REAL T|op_points ) , SETTER FOR Top	Setting the form top coordinate.
ENUMERATION {positioning} :         'KEEP_ON_SCREEN|_AND_SAME_DISPLAY' ,         'CENTER_ON_SCREEN|_IGNORE_L_T_VALUES' ,         'POSITION_AS_IS|_BY_L_T_VALUES' .	Possible positioning options.
METHOD Set_position (      REAL L|eft_position ,      REAL T|op_position ,      {positioning} Options|_positions )	Setting the form top left coordinates (on entire screen).
FUN Exclude_taskbar (      {rect} R|ectagle ) ==> {rect} , DEPRECATED('Platform dependent')
METHOD Width|_points ==> REAL	Form width.
METHOD Set_width ( REAL W|idth_points ) , SETTER FOR Width	Setting the form width.
METHOD Height|_points ==> REAL	Form height.
METHOD Set_height ( REAL H|eight_points ) , SETTER FOR Height	Setting the form height.
ENUMERATION {sizing|_options} :         'FIT_TO_DISPLAY' ,         'FIT_TO_DESKTOP' ,         'SIZE_AS_IS|_BY_W_H_VALUES' .	Possible sizing options.
METHOD Set_size|_of_form (      REAL Set_width|_points_if_negative_dont_change ,      REAL Set_height|_points_if_negative_dont_change ,      {sizing} Options|_sizing )	Setting the form size.
METHOD Stay_on_top|_of_Z_order ( BOOL Top|most_form )	Setting (or resetting) for the form its "stay on top" option.
METHOD Set_size_min|imal (      REAL Width|_max_640_pixels ,      REAL Height|_max_480_pixels ) , DEPRECATED('Platform dependent')

------------------------------------------------------------- 'client size'

METHOD Client_width ==> REAL	Form client area width.
METHOD Client_height ==> REAL	Form client area height.
METHOD Client_pos|ition ==> {point}	Form client area top-left position relative to entire form rectangle.
METHOD Set_client_size (      REAL W|idth_points ,      REAL H|eight_pointts ,      {sizing} Options|_sizing )	Setting form size on base of desired client area size.

------------------------------------------------------------- 'form events'

Override the 'command' method to handle events launching of another instance of you application by users. To provide it firing, use {Single_instance} instead of the {Screen} class. When the 'command' method is called, it is possible to get the secondary application parameters via usual Count_param and Parameter functions from the {System_functions} class.

Override the 'accept' method to handle drop files event and to return TRUE in case when the drop for a given set of files is acceptable. The files list is available via Count_param and Parameter functions from the {System_functions} class, both in the 'accept' and the 'command' method. Teh 0th parameter is not used as a part of the file list. The 'command' is called to handle the drop files event after the 'accept' was returning TRUE before (when the mouse button is released to perform the allowed drop files operation).

------------------------------------------------------------- 'show / hide'

 

METHOD Visible|_form ==> BOOL	TRUE when the form is visible.
METHOD Hidden|_form ==> BOOL
METHOD Show|_form	Show the form.
METHOD Hide|_form	Hide the form.
ENUMERATION {reason_closing} :         'USER|_CLOSES_FORM' ,         'PROGRAM|_CLOSES_FORM' ,         'SHUTDOWN|_SYSTEM_OR_USER_LOGOFF' .	Possible form close reasons.

BOOL Do_not_close|_even_on_shutdown|_preventing_system_to_restart_or_shutdown

BOOL Closed|_do_not_try_show_it_again , READ

TRUE if closed. It is not possible to operate further with a closed form.

---------------------------------------------------- 'messages & questions'

METHOD message|_show ( STR Text|_show ) , PUBLIC	The method to show some text message, usually in a separate dialog window..
METHOD ask|_question_yes_no ( STR A|nswer_text ) ==> BOOL , PUBLIC	The method to ask some question with 2 possible answers (Yes / No) and waiting for the answer from a user.

--------------------------------------------- 'child modal dialog (single)'

METHOD Current_modal_dialog ==> {Form}

Returns current modal form of class {Dialog} shown. Only one modal dialog can be active at once.

-------------------------------------------------------------------- 'menu'

To create and pop up a menu the method Popup_menu is used. Its single parameter is a string containing item definitions separated by new line characters (#NL). It is convenient to use a multi-line string constant started with the symbol @. In such case for all the lines ending with a string literal a new line sequence is added. To organyze nested menu items add following the item which is then parent for a nesting menu, the string constant "(" (and to end the nesting level, the string ")"). Each string contains a menu item definition and for real menu items it should start from the item alias in a form "IDENTIFIER:", where a colon separates a menu item alias from the menu item text definition. It is also possible to specify togethewr with an alias some additional properties such as "disabled" or "checked", placing correspondent string constants comma separated. E.g.:

  Popup_menu(@
  "COPY,disabled:	&Copy	[Ctrl-C]"
  "CUT,disabled:	C&ut	[Ctrl-X]"
  "PASTE:		&Paste	[Ctrl-V]"
  "-"
  "Mode..."
  "("
    "AUTO,checked:	&Auto"
    "Manual:		&Manual"
  ")"
  "EXIT:		&Exit")

A separate string "-" creates a visual group separator. A single symbol "&" in a menu item text creates a shortcut symbol which can be used to select the item by a key combination ALT+ the next character. (But in someenvironments like Java such shortcut has not effect). To use the symbol '&' itself as a part of a menu item text, double it. To handle menu items, it is necessary to redefine menu item event handler:
OVERRIDE menu(STR Alias) : ...

------------------------------------------------------- 'work with columns'

   

ENUMERATION {layout|_on_form} :         'CENTER||CLIENT|_ALIGNED' ,         'LEFT|_ALIGNED' ,         'RIGHT|_ALIGNED' ,         'TOP|_ALIGNED' ,         'BOTTOM|_ALIGNED' .	Possible layouts for columns.
METHOD Column_layout|_by_its_alias (      STR Alias|_of_column ) ==> {layout}
STRUCTURE {sizes_col|umn}       REAL Width|_points       REAL Label|_width_points       BOOL Align_right|_labels       STR Nested_in|_parent_column_alias .	Possible layouts for columns.
FUNCTION DEFAULT_SIZES|_FOR_COLUMN ==> {sizes_col}	Default sizes value to pass as the 3rd parameter while create a column. The same as to create a structure of type {sizes_col} not assigning any its field: new_column(..., ..., {sizes_col})
METHOD Columns_count ==> INT	Total amount of columns on the form.
METHOD Column_alias|_by_index (      INT Index|_of_column INDEXING STR ) ==> STR
METHOD Column_handle ( STR Alias|_of_column ) ==> INT

STR Current_column|_alias , READ

Current column (used as an implicit parameter in some methods to operate with columns).

-------------------------------- 'align TOP/BOTTOM aligned column controls'

         

ENUMERATION {controls_layout|_mainly_for_horizontal_columns} :         'CONTROLS_LEFT||CONTROLS_DEFAULT' ,         'CONTROLS_RIGHT|_ALIGNED' ,         'CONTROLS_CENTER|_ALIGNED' ,         'CONTROLS_JUSTIFY||CONTROLS_JUSTIFIED' ,         'CONTROLS_LEFT_LAST_RIGHT' ,         'CONTROLS_TOP_TO_BOTTOM' ,         'CONTROLS_VERTICAL_2|_COLUMNS' ,         'CONTROLS_LEFT_LABELS_ABOVE' .
METHOD Current_column_layout ==> {controls_layout}
METHOD Column_controls_layout (      STR Alias|_of_column ) ==> {controls_layout}
METHOD Set_column_controls_layout ( {controls_layout} CL|ayout_set )
METHOD Column_uses_margins ( STR Alias|_of_column ) ==> BOOL
METHOD Set_column_margins ( STR Alias|_column , BOOL Use_margins )
METHOD Column_width|_by_alias ( STR Col|umn_alias ) ==> REAL	Column width.
METHOD Set_column_width|_use_only_for_LEFT_RIGHT_aligned (      REAL New_width )	Set the column width. This opertion usually is applicable for columns aligned 'LEFT', 'RIGHT' or 'CENTER' (and not applicable to 'TOP'/'BOTTOM' aligned columns).
METHOD Set_column_width_by_alias|_use_only_for_LEFT_RIGHT_aligned (      STR Col|umn_alias ,      REAL New_width )
METHOD Set_column_label_width ( REAL L|abel_widht )	Set the current column label width. In each line of a column (except aligned 'TOP'/'BOTTOM') a control and its label can be placed (where the label also is a control of the class {Label}). But the label placed left to a control should fit the label width specified, otherwise it is located also in a separate line, above the control to which it is concerning. Note that a control anchored bottom always is placed in a separate line. It is always possible to force to locate a control in a separate line (prepending it either with a wide label or placing the second empty label before it). If the label width is specified as -1, then all the controls and labels are placed in its own lines always.
METHOD Column_height|_by_alias ( STR Col|umn_alias ) ==> REAL	The current column height.
METHOD Set_column_height|_use_only_for_BOTTOM_TOP_aligned (      REAL New_height )	Setting the current column height. This opertion is applicable only to columns aligned 'TOP' or 'BOTTOM'.
METHOD Set_column_height_by_alias|_use_only_for_BOTTOM_TOP_aligned (      STR Col|umn_alias ,      REAL New_height )
METHOD Set_column_auto_arrange|_controls (      BOOL Enable|_auto_arrange_TRUE_is_default )	Setting for the current column its "auto-arrange controls" property. By default, all the columns created are auto-arranged. After setting value FALSE, controls in the column no more moved/sized automatically without your code doing this explicitly. But, on some platforms such technique of manual arranging controls is not available and calls of this method are just ignored.
FUN Set_default_font|_for_all_forms_created_later (      {Screen} Screen|_holder ,      STR Face|_font ,      REAL Size|_font )
METHOD Set_column_font|_default_for_controls (      STR Face|_font ,      REAL Size|_font ,      STR Styles|_font )	Setting the current column default controls font. This opertion allows to specify at once font attributes assigned by default to further controls creating on the current column.

---------------------------------------- 'configuration for mobile devices'

ENUMERATION {mobile_config|uration} :         'SINGLE_TOP_BOTTOM' ,         'ALL_TOP_BOTTOM|_VISIBLE_SWIPE_IF_NEEDED' .	Available options for columns visibility in case of a mobile device as a target. 'SINGLE_TOP_BOTTOM' means that at once the user can see only one 'TOP'-aligned and / or one 'BOTTOM'-aligned column (in case when several such columns were defined on a form). In such configuration swiping up/down on correspondent columns will switch a visible 'TOP'/'BOTTOM' columns. Thereas 'ALL_TOP_BOTTOM' means that all the top/bottom aligned columns are viewing at a time, but if these are not fit the screen in height, swiping will pan entire form vertically allowing access the form invisible parts.
METHOD Mobile_configuration|_of_form ==> {mobile_config}	Returns the form mobile configuration for 'TOP' / 'BOTTOM' aligned columns.
METHOD Set_mobile_configuration|_of_form (      {mobile_config} MC|onfiguration_to_set )	Setting the form mobile configuration for 'TOP' / 'BOTTOM' aligned columns.

---------------------------------------------------------- 'active control'

METHOD Get_active|_control ==> {Control}	Returns the active (focused) control of the form.
METHOD Set_active|_control (      {Control} C|ontrol_to_activate ) , SETTER FOR Get_active	Setting the active (focused) control of the form.

------------------------------------------------ 'default / cancel buttons'

{Button} Default_button , READ

Current default button on the form (of the class {Button}). Only one button can be defined as the default at a time on a form. It can be clicked by the keyboard key ENTER if such key is not handled by a current active control on a form. E.g. the ENTER key can be used in a {Memo} control to insert symbols #NL to its text.

{Button} Cancel_button , READ

Like for the default button, but uset to store current cancel button. It can be clicked by the keyboard key ESCAPE (if such key is not handled, too).

-------------------------------------------------------------- 'click info'

METHOD Get_popup_point ==> {Geometry}.{point}	Returns current popup point on form used while pop up a menu operation. It depends on current event handling: in case of the click event e.g. coordinates are located at the bottom left point of a control clicked. In case of mouse up/down events, exact coordinates on the form of a pointing device used are returned.
FUNCTION Mouse_cur|sor_position_current ==> {point}	Returns a mouse coordinates on form (in points) globally. This method can be used not only in mouse handling events (e.g. while a timer tick event).
FUNCTION Set_mouse_cur|sor_position (      {point} New|_position ) , DEPRECATED('Platform dependent')	Returns a mouse coordinates on form (in points) globally. This method can be used not only in mouse handling events (e.g. while a timer tick event).
FUNCTION Mouse_pressed|_button (      {button} Button|_to_check ) ==> BOOL	Returns TRUE if a certain mouse button is pressed.
ENUMERATION {button|_mouse} :         'NO_B|UTTON' ,         'LMB|_LEFT_MOUSE_BUTTON' ,         'RMB|_RIGHT_MOUSE_BUTTON' ,         'MMB|_MIDDLE_MOUSE_BUTTON' ,         'XB1|_MOUSE_BUTTON' ,         'XB2|_MOUSE_BUTTON' .	Available mouse buttons.

------------------------------------------------------- 'keyboard key info'

ENUMERATION {action|_accept_by_default} :         'ACCEPT|ED_KEY' ,         'DECLINE|D_KEY' .	Possible actions (in some events returning an action).
STRUCTURE {key_info|rmation}       INT Special|_key_pressed       STR Char|_pressed       BOOL Right|_key_ctrl_alt       BOOL Caps|_lock_key_is_fixed_down||Capital|s       BOOL Shift|_pressed       BOOL Ctrl||Control|_pressed       BOOL Alt|_pressed       BOOL Win|_pressed       BOOL Ignore|_do_not_handle .	Data about currently fired (pressed down or released) keyboard key are stored in the structure defined here (in the Key field of the form).

{key_info} Key|_information_LOCAL

Information about key pressed (or released) actual while handling keyboard events.

--------------------------------------- 'Keyboard (w\o events if possible)'

FUNCTION Global_key|_pressed ( INT Key|_of_state ) ==> BOOL

Returns TRUE if the specified Key was pressed and is not yet released. This method can be called in any event handlers, not only while handling keyboard events.

----------------------------------------------------------- 'change events'

METHOD Notify_value_change (      {Control} C|ontrol_value_changed_of ) , CALLBACK	The method to be called internally to handle value_change event (and to force calling the Any_change method at the end).
FUNCTION Notify_sel_change|d_LOCAL_called_from_AL4_form (      {Form} Form|_working ) , CALLBACK	The internal method to provide handling selection change events and force the method Any_change calling at the end.
METHOD In_any_change|_handler ==> BOOL	Returns TRUE, if the Any_change method is already running.
METHOD Any_change	The method for handling some changes made in controls of the form. This is the method where the hidden and the disabled methods are called for controls (specified in can_hide[] / grayable[]) and the column_hidden is called for each column to decide which of them to show / hide or disable / enable.
METHOD Suspend_layout , PUSH	Suspending any controls or columns re-arranging. Should be used in PUSH blocks at the header part. The method resume_layout alternative to the Suspend_layout is called automatically (and instantly) at the end of a PUSH block.

-------------------------------------------------- 'long operations dialog'

BOOL Can_stop_long_operation|_set_to_FALSE_to_prevent_dialog_show_and_stop_operation

INT In_long_operation|_level

{event} Current_event|_kind_to_use_in_long_operation_dialog_in_default_description

Current (the last) event handling.

STR Alias_current_event

Text alias of a sender control initialted the last event, used while long operations handling (to show a reason of a long operation).

--------------------------------------------------- 'save / restore bounds'

 

METHOD Save_bounds (      STR App|lication_name ,      STR Section|_name ,      STR What|_to_save_Left_Top_Width_Height_by_1st_letters )	Saving bounds of the form using the {Configuration} class. It is necessary to specify a non-empty application name (App), optional section name (Section) and to list letters specified which parameters should be saved (W - Width, H - Height, L - Left, T - Top, * or empty string in the What - all the bounds).
METHOD Restore_bounds (      STR App|lication_name ,      STR Section|_name ,      STR What|_to_load_Left_Top_Width_Height_by_1st_letters )	Restoring bounds of the form using the {Configuration} class. Parameters should match those specified while saving the bounds (in the Save_bounds method).
ENUMERATION {state|_of_form} :         'NORMAL|_STATE' ,         'MINIMIZED|_STATE' ,         'MAXIMIZED|_STATE' .	Possible states of a form.
METHOD State|_normal_minimized_maximized ==> {state}	Returns current state of the form.
METHOD Set_state ( {state} Value|_to_set ) , SETTER FOR State

------------------------------------------------------- 'queue of messages'

 

METHOD Process|_all_messages || Process_all_events

------------------------------------------------ 'for {Dialog} inheritance'

BOOL Ready|_answered , READ

TRUE, if the dialog was already answered.

STR Answer|_set_in_result , READ

A text value which is representing an answer form the user. When the dialog method ready is called this answer is passed and stored here. After returning to a point where the dialog results are handling, your code can analyze this value to decide what to do further.

--------------------------------------- 'adjusting columns size / position'

     

STRUCTURE {i_rect|angle}       INT Left|_position       INT Top|_position       INT W|idth_size_horizontal       INT H|eight_size_vertical .
FUN Do_adjust_columns (      {Form} F|orm_object ,      INT W|idth_client_in_pixels ,      INT H|eight_client_in_pixels ) , CALLBACK
STRUCTURE {c_rep|osition_control}       {Control} Control_|to_reposition_       {point} Loc|ation       REAL W|idth_control       REAL H|eight_control       BOOL Top_same|_with_next_control .
FUN Do_adjust_controls (      {Form} F|orm_object ,      INT CH|andle_column ) , CALLBACK
METHOD Invalidate

---------------------- 'especially for Free Pascal to call from {AL4_form}'

 

METHOD Make_tool_window ( BOOL Yes|_make_tool_window )

END