{Form|_containing_controls}

CLASS {Form|_containing_controls} , UNTESTED, DESTRUCTORS :

Класс формы. Предназначен для создания ваших наследников, в которых определяется состав компонентов формы и переопределяются методы для организации обработки событий формы и её компонентов. В визуальной библиотеке AL-IV, все визуальные компоненты размещаются в колонках, а колонки - на форме. Более вложенные иерархии не допускаются, исключая слишком сложные конфигурации формы, которые не могут быть нормально отображены на маленьких экранах.

----------------------------------------------------- 'создание / закрытие'

STR Alias|_form

Строковое "прозвище" формы. Может быть полезно для различения форм оператором CASE.

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

Список дочерних контролов формы (не колонок, а именно всех контролов на всех колонках).

INT Handle|_native , READ

Дескриптор формы, связывающий ее с неативным объектом, представляющим форму в целевой системе.

{Screen} Screen_|object_ , INIT

Ссылка на объект класса {Screen} (который должен быть единственным в приложении).

------------------------------------------------ 'нативный дескриптор окна'

 

METHOD Window_handle ==> INT , DEPRECATED('Platform dependent')	Дескриптор окна формы. Не путайте его с дескриптором нативного объекта формы. Данный дескриптор окна используется в ОС Windows (MS) для идентификации окон.
METHOD Show_application_button|_for_the_form (      BOOL Value|_show ) , DEPRECATED('Platform dependent')

------------------------------------------------------ 'заголовок, границы'

METHOD Caption|_form ==> STR	Строка заголовка формы.
METHOD Set_caption ( STR V|alue_caption ) , SETTER FOR Caption	Смена заголовка формы.

BOOL No_frame|_was_set , READ

Установка (или снятие) для формы режима "без рамки". Эта опция зависит от целевой платформы и может быть просто проигнорирована.

BOOL No_borders , READ

Установка (или снятие) для формы режима "без границы". Эта опция зависит от целевой платформы и может быть просто проигнорирована.

BOOL Custom_colors , READ

Установка цветов формы.

INT Custom_foreground|_color , READ

INT Custom_background|_color , READ

-------------------------------------------------------- 'позиция и размер'

   

METHOD Bounds|_of_form_in_points ==> {rect}	Прямоугольник, занимаемый формой на всем доступном экране. В некоторых случаях (например, в много-мониторных системах), координаты могут быть отрицательными.
METHOD Set_bounds ( {rect} V|alue_new_bounds )
METHOD Left|_position_points ==> REAL	Левая координата формы на всем доступном экране. В некоторых случаях координаты могут быть отрицательными.
METHOD Set_left ( REAL L|eft_points ) , SETTER FOR Left	Установка левой координаты формы.
METHOD Top|_position_points ==> REAL	Верхняя координата формы . В некоторых случаях координаты могут быть отрицательными.
METHOD Set_top|_position ( REAL T|op_points ) , SETTER FOR Top	Установка верхней координаты формы.
ENUMERATION {positioning} :         'KEEP_ON_SCREEN|_AND_SAME_DISPLAY' ,         'CENTER_ON_SCREEN|_IGNORE_L_T_VALUES' ,         'POSITION_AS_IS|_BY_L_T_VALUES' .	Возможные опции позиционирования.
METHOD Set_position (      REAL L|eft_position ,      REAL T|op_position ,      {positioning} Options|_positions )	Установка левой верхней координаты формы на экране.
FUN Exclude_taskbar (      {rect} R|ectagle ) ==> {rect} , DEPRECATED('Platform dependent')
METHOD Width|_points ==> REAL	Ширина формы.
METHOD Set_width ( REAL W|idth_points ) , SETTER FOR Width	Установка ширины формы.
METHOD Height|_points ==> REAL	Высота формы.
METHOD Set_height ( REAL H|eight_points ) , SETTER FOR Height	Установка высоты формы.
ENUMERATION {sizing|_options} :         'FIT_TO_DISPLAY' ,         'FIT_TO_DESKTOP' ,         'SIZE_AS_IS|_BY_W_H_VALUES' .	Возможные опции изменения размера формы.
METHOD Set_size|_of_form (      REAL Set_width|_points_if_negative_dont_change ,      REAL Set_height|_points_if_negative_dont_change ,      {sizing} Options|_sizing )	Установка размера формы.
METHOD Stay_on_top|_of_Z_order ( BOOL Top|most_form )	Установка для формы режима "поверх всех".
METHOD Set_size_min|imal (      REAL Width|_max_640_pixels ,      REAL Height|_max_480_pixels ) , DEPRECATED('Platform dependent')

------------------------------------------------------- 'клиентский размер'

METHOD Client_width ==> REAL	Ширины клиентской области формы.
METHOD Client_height ==> REAL	Высота клиентской области формы.
METHOD Client_pos|ition ==> {point}	Верхняя левая координата клиентской области формы относительно всей формы.
METHOD Set_client_size (      REAL W|idth_points ,      REAL H|eight_pointts ,      {sizing} Options|_sizing )	Установка размера формы на основе желаемого размера клиентской области формы.

------------- 'перетаскивание файлов, запуск другого экземпляра приложения'

----------------------------------------------------------- 'события формы'

Переопределение метода 'command' позволяет обрабатывать события запуска других экземпляров приложения. При этом список параметров запущенного экземпляра становится доступен через функции Count_param, Parameter из {System_functions}. Стобы событие command работало, и обеспечивался единственный экземпляр приложения, следует вместо класса {Screen} в функции Main визуального приложения использовать класс {Single_instance}.

Переопределение метода 'accept' позволяет обрабатывать события бросания файлов на форму (в результате перетаскивания мышью). Если ваш 'accept' возвращает TRUE, набор файлов считается допустимым и последующее отпускание клавиши мыши модет приводить к срабатыванию события 'command' для обработки собственно бросания списка файловс на форму. Сам список файлов доступен через функции Count_param и Parameter класса {System_functions} (при этом параметр с индексом 0 не используется).

--------------------------------------------------- 'отображение / скрытие'

 

METHOD Visible|_form ==> BOOL	TRUE если форма видимая.
METHOD Hidden|_form ==> BOOL
METHOD Show|_form	Отображает форму.
METHOD Hide|_form	Скрывает форму.
ENUMERATION {reason_closing} :         'USER|_CLOSES_FORM' ,         'PROGRAM|_CLOSES_FORM' ,         'SHUTDOWN|_SYSTEM_OR_USER_LOGOFF' .	Возможные причины закрытия формы.

BOOL Do_not_close|_even_on_shutdown|_preventing_system_to_restart_or_shutdown

BOOL Closed|_do_not_try_show_it_again , READ

TRUE если форма закрыта. После закрытия формы ее нельзя больше отобразить.

------------------------------------------------------ 'сообщения / вопрос'

METHOD message|_show ( STR Text|_show ) , PUBLIC	Метод для отображения некоторого текстового сообщения, обычно в отдельном диалоговом окне.
METHOD ask|_question_yes_no ( STR A|nswer_text ) ==> BOOL , PUBLIC	Метод для задания вопроса, имеющего 2 возможных ответа (Да / Нет) и ожидания ответа от пользователя.

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

METHOD Current_modal_dialog ==> {Form}

Возвращает текуший подчиненный модальный диалог. Только один модальный диалог может быть активным для формы.

-------------------------------------------------------------------- 'меню'

Для создания и вызова всплывающего меню используется метод Popup_menu. Его единственный параметр - это строка, состоящая из определний пунктов меню, разделённых символами конца строки. Удобно использовать задание многострочной строчной константы с перфиксным символом @. В этом случае символ возврата каретки добавляется автоматически, если строка завершается строчным литералом. Для организации вложенных меню, следом за пунктом, являющимся родительским, должна быть отдельно расположена строка, содержащая только символ "(". Аналогично, строка ")" завершает уровень. Каждая строка, соответствующая пункту меню, может (и должна) начинаться с префикса вида "ИДЕНТИФИКАТОР:" (двоеточие отделяет назначенный пункту меню синоним от текста пункта меню, следующего за двоеточием). Так же, возможно указание вместе с синонимом дополнительных атрибутов через запятую: disabled, checked. Например:

  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")

Отдельная строка "-" создаёт визуальный разделитель групп (обычно отображается как горизонтальная линия в меню). Одиночный символ "&" в определении пункта меню задаёт символ-ускоритель для быстрого выбора элемента (нажатием ALt+следующий символ). Но в некоторых средах этот символ просто игнорируется (Java). Для использования самого символа '&' в тексте меню, его следует удвоить. Для обработки пунктов меню следует переопределить обработчик menu:
OVERRIDE menu(STR Alias) : ...

---------------------------------------------------- 'управление колонками'

   

ENUMERATION {layout|_on_form} :         'CENTER||CLIENT|_ALIGNED' ,         'LEFT|_ALIGNED' ,         'RIGHT|_ALIGNED' ,         'TOP|_ALIGNED' ,         'BOTTOM|_ALIGNED' .	Доступные выравнивания для колонок.
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 .	Доступные выравнивания для колонок.
FUNCTION DEFAULT_SIZES|_FOR_COLUMN ==> {sizes_col}	Размеры для колонки по умолчанию, для передачи в качестве третьего параметра в вызове new_column - то же, что и просто передать генератор новой структуры типа {sizes_col} без присваивания каких-либо значений ее полям. Например: new_column(..., ..., {sizes_col})
METHOD Columns_count ==> INT	Общее количество колонок на форме.
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

Текущая колонка (используется как неявный параметр в некоторых операциях с колонками).

-------------------------------- '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	Ширина колонки.
METHOD Set_column_width|_use_only_for_LEFT_RIGHT_aligned (      REAL New_width )	Установка ширина колонки. Эта операция применима только для колонок, выровненных влево ('LEFT'), вправо ('RIGHT') или по центру ('CENTER'), и не применима к колонкам, выровненных по верхнему ('TOP') или нижнему ('BOTTOM') краю.
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 )	Установка ширина метки текущей колонки. В каждой строке колонки (кроме выровненных вверх - 'TOP' или вниз - 'BOTTOM') может размещаться контрол и его метка (где метка также является контролом класса {Label}). Но контрол-метка, размещаемая слева от контрола, должна по размеру вписываться в заданную этим методом ширину метки колонки, иначе она размещается в отдельной строке, выше контрола, к которому она относится. Контрол, расширенный вниз (Set_anchor_bottom(TRUE)) всегда размещается в отдельной строке. Всегда возможно форсировать размещение метки в отдеьной строке (например, добавив после метки еще одноу - пустую - метку). Если ширина метки колонки задана равной -1, то в колонке метки всегда размещаются в отдельных строках.
METHOD Column_height|_by_alias ( STR Col|umn_alias ) ==> REAL	Высота текущей колонки.
METHOD Set_column_height|_use_only_for_BOTTOM_TOP_aligned (      REAL New_height )	Установка высоты колонки. Эта операция применима только к колонкам, выровненным вверх ('TOP') или вниз ('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 )	Установка для текущей колонки его свойства "автоматическое размещение контролов". По умолчанию, для всех создаваемых на форме колонок, это свойство устанавливается в TRUE. При установке значения FALSE, контролы в колонке более не перемещаются и не измененяют свой размер автоматически, без того, чтобы это делалось вашим кодом. Но, на некоторых платформах такой механизм "ручного" размещения контролов в колонках не поддерживается, и вызов данного метода просто игнорируется.
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 )	Установка для текущей колонки атрибутов шрифта по умолчанию. Позволяет настроить шрифт для всех контролов, создаваемых на данной колонке, созданных после этого вызова.

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

ENUMERATION {mobile_config|uration} :         'SINGLE_TOP_BOTTOM' ,         'ALL_TOP_BOTTOM|_VISIBLE_SWIPE_IF_NEEDED' .	Доступные опции видимости колонок для случая мобильных устройств. 'SINGLE_TOP_BOTTOM' означает, что одновременно может быть отображаена только одна выровненная по верхнему и / или нижнему краю "колонка", и свайпом по такой колонке вниз/вверх пользователь может выбрать, какие именно колонки следует отображить. Опция 'ALL_TOP_BOTTOM' означает, что отображаются все выровненные вверх/вниз колонки, но если при этом форма не вмиещается по вертикали, то свайпингом вверх-вниз форму можно скроллировать, чтобы увидеть невидимые в данный момент ее участки (паннинг).
METHOD Mobile_configuration|_of_form ==> {mobile_config}	Возвращается для формы мобильная конфигурация для колонок, выровненных вверх ('TOP') или вниз ('BOTTOM').
METHOD Set_mobile_configuration|_of_form (      {mobile_config} MC|onfiguration_to_set )	Установка для формы мобильной конфигурация для колонок, выровненных вверх ('TOP') или вниз ('BOTTOM').

------------------------------------------- 'активный визуальный компонент'

METHOD Get_active|_control ==> {Control}	Возвращает активный контрол формы (находящийся в фокусе ввода).
METHOD Set_active|_control (      {Control} C|ontrol_to_activate ) , SETTER FOR Get_active	Устанавливает активный контрол формы (переводит его в фокус ввода с клавиатуры).

----------------------------------------------------- 'события компонентов'

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

{Button} Default_button , READ

Текущая кнопка по умолчанию на форме (класса {Button}). Только одна кнопка может быть сделана "кнопкой по умолчанию" на форме. Такая кнопка может быть нажата клавишей ENTER (в случае, если клавиша ENTER не обрабатывается текушим активным контролм для других целей - например, в {Memo} клавиша ENTER может вставлять симолы #NL в текст).

{Button} Cancel_button , READ

Подобно кнопке по умолчанию на форме, но для храения текущей кнопки "отмены" операции. Нажимается на клавиатуре клавишей ESCAPE, также - если не обработано текущим контролом.

------------------------------------- 'данные о состоянии указателя (мыши)'

METHOD Get_popup_point ==> {Geometry}.{point}	Возвращает текущие координаты на форме для точки всплытия меню. В зависимости от обрабатываемого события, возвращаются либо точные координаты на форме (при событиях mouse_down, mouse_up, mouse_double_click), либо нижняя левая точка активированного контрола.
FUNCTION Mouse_cur|sor_position_current ==> {point}	Возвращает координаты мыши на форме (в поинтах), глобально (в том числе не только при обработке событий мыши, например, в событии тика таймера timer).
FUNCTION Set_mouse_cur|sor_position (      {point} New|_position ) , DEPRECATED('Platform dependent')	Возвращает координаты мыши на форме (в поинтах), глобально (в том числе не только при обработке событий мыши, например, в событии тика таймера timer).
FUNCTION Mouse_pressed|_button (      {button} Button|_to_check ) ==> BOOL	Возвращает TRUE, если нажата указанная кнопка мыши.
ENUMERATION {button|_mouse} :         'NO_B|UTTON' ,         'LMB|_LEFT_MOUSE_BUTTON' ,         'RMB|_RIGHT_MOUSE_BUTTON' ,         'MMB|_MIDDLE_MOUSE_BUTTON' ,         'XB1|_MOUSE_BUTTON' ,         'XB2|_MOUSE_BUTTON' .	Доступные кнопки мыши.

-------------------------------------------------------------- 'клавиатура'

ENUMERATION {action|_accept_by_default} :         'ACCEPT|ED_KEY' ,         'DECLINE|D_KEY' .	Доступные кнопки мыши (используется в некоторых событиях, возвращающих действие).
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 .	Данные о нажатии (или отпускании) клавиши на клавиатуре сохраняются в такой структуре, в поле объекта формы Key.

{key_info} Key|_information_LOCAL

Информацио о кнопке клавиатуры (нажатой или отпущенной). Актуальна в процессе обработки событий клавиатуры.

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

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

Возвращает TRUE, если указанная клавиша Key была нажата, но не была еще отпущена. Данный метод может быть вызван при обработке любых событий, а не только в обработчиках событий клавиатуры.

----------------------------------------------------------------- 'таймеры'

------------------------------------------------------- 'события изменений'

METHOD Notify_value_change (      {Control} C|ontrol_value_changed_of ) , CALLBACK	Метод для внутренней инициации события value_change (обеспечивает гарантию вызова Any_change по окончании обработки).
FUNCTION Notify_sel_change|d_LOCAL_called_from_AL4_form (      {Form} Form|_working ) , CALLBACK	Внутренний метод для обеспечения обработки событий изменения области выделения в некоторых видах контролов.
METHOD In_any_change|_handler ==> BOOL	Возвращает TRUE, если метод Any_change уже вызван.
METHOD Any_change	Метод для обработки события любых изменений в состоянии контролов формы. Именно в нем вызываются методы disabled, hidden и column_hidden для определения того, в каком состоянии (скрыто / недоступно) должны находиться контролы и колонки.
METHOD Suspend_layout , PUSH	Приостанавливает любые операции переразмещения контролов и колонок на форме. Должен использоваться в заголовке блока PUSH. Метод resume_layout вызывается автоматически (и гарантированно) по окончании работы такого блока.

------------------------------- 'события для скрытия / запрета компонентов'

-------------------------------------------------- '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

Текущее (последнее) обрабатываемое событие.

STR Alias_current_event

Текстовая метка контрола, вызывавшего последнее событие. Используется для отображения в диалоге о длинной операции.

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

 

METHOD Save_bounds (      STR App|lication_name ,      STR Section|_name ,      STR What|_to_save_Left_Top_Width_Height_by_1st_letters )	Сохраняет границы формы в хранилище конфигурации (класса {Configuration}). Необходимо задать непустое имя приложения (App), необязательное имя секции (Section) и перечень сторон для сохранения (W - ширина, H - высота, L - левая сторона, T - верхняя сторона, * или пустая строка в What - все границы).
METHOD Restore_bounds (      STR App|lication_name ,      STR Section|_name ,      STR What|_to_load_Left_Top_Width_Height_by_1st_letters )	Восстанавливает границы формы из хранилище конфигурации. Параметры должны быть те же, что и при сохранении границ (в методе Save_bounds).
ENUMERATION {state|_of_form} :         'NORMAL|_STATE' ,         'MINIMIZED|_STATE' ,         'MAXIMIZED|_STATE' .	Возможные состяния формы.
METHOD State|_normal_minimized_maximized ==> {state}	Возвращает текущее состояние формы.
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, если для диалога уже был получен ответ от пользователя.

STR Answer|_set_in_result , READ

Текстовая строка, представляеющая собой ответ, полученный от пользователя в процессе работы данного диалога. Когда вызывается метод ready диалога, эта строка передается в вашем коде в качестве ответа. После возвращения управления в точку, где обрабатывается ответ диалога, эта строка может быть проанализирована, чтобы опредить, что делать дальше.

--------------------------------------- '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