ask_form()/open_form()
Detailed Description
This module describes how to generate a custom form.
The following keywords might appear at the beginning of the 'form' argument (case insensitive):
STARTITEM number
where number is a number of input field the cursor will stand on. By default the cursor is in the first field of the dialog box. The input fields are numbered from 0 (the first field is field 0).
BUTTON name caption
Alternative caption for a button. It may contain the character to highlight in this form: ~Y~es Valid button names are: YES, NO, CANCEL For example: BUTTON YES Please do BUTTON NO Nope BUTTON CANCEL NONE
By default the NO button is not displayed. If it is displayed, then the return value of the function will be different! (see the function description)
Empty text means that there won't be any corresponding button. (you may also use NONE as the caption to hide it)
A * after the button name means that this button will be the default:
BUTTON CANCEL* Cancel
Next, if the dialog box is kept in IDA.HLP, the following may appear: (this defines help context for the whole dialog box)
[]
If the form is not in IDA.HLP file, then it can have a built-in help message. In this case the help screen should be enclosed in the following keywords:
HELP .... .... .... ENDHELP
Each keyword should be on a separate line.
Next there must be the title line and two empty lines. Most of the text in the dialog box text string is copied to the dialog without modification. There are three special cases:
- dynamic labels (format parameters)
- callback arguments
- input fields
For example, this dialog box:
------ format: Sample dialog box
This is sample dialog box for A using address %$
<~E~nter value:N::18::>
------
Contains two dynamic labels (text A and address %$) and one input field (numerical input box with the label "Enter value").
Parameters for the dynamic labels and input fields are taken from the function's input arguments (va_list). The corresponding argument should contain a pointer (sic, pointer) to the value to be displayed.
The dialog box above should be called as
Dynamic labels are used to specify variant parts of the dialog box text. They use the following syntax:
nT
where n - optional decimal field ID, which may be used in the form_actions_t calls to get/set label value at runtime T - a character specifying type of input field. All input field types (except B and K) are valid format specifiers. See below for the list.
There are two special specifiers for callbacks:
The combination '%/' corresponds to a callback function that will be called when any of the fields is modified. The callback type is formchgcb_t. There can be only one such callback.
The combination '%*' is used to store user data (void *) in the form. This data can be later retrieved from the formchgcb_t callback via the form action method get_ud().
Input fields use the following syntax:
<label:type:width:swidth:[]>
where label - any text string serving as label for the input field the label may contain an accelerator key like this: "~O~pen" (O is the accelerator key; Alt-O will work too) type - a character specifying type of input field. The form() function will perform initial validation of value specified by the user and convert it appropriately. See table of input field types below. The type can be followed by a decimal number, an input field ID. width - for A, I, T, X: decimal number specifying size of the buffer passed for text input fields (including terminating 0). if omitted or <0, assumed to be at least MAXSTR
for B, k: the code generated when the user presses the button (passed to the button callback) for f (path to file) this attribute specifies the dialog type: 0-'open file' dialog box 1-'save file' dialog box for F (folder) it is ignored (buffer is assumed to be at least QMAXPATH long) for b (dropdown list) this attribute specifies the readonly attribute: 0 - read-only dropdown list > 0 - editable dropdown list for i, q: decimal number specifying maximum possible number of characters that can be entered into the input field for the rest of controls: this field is ignored swidth -decimal number specifying width of visible part of input field. this number may be omitted. []- help context for the input field. you may replace the help context with '::' (two colons) if you don't want to specify help context. The help context is a number of help page from IDA.HLP file.
Input field types va_list parameter ----------------- -----------------
A - UTF-8 string char* at least MAXSTR size, obsolete, see below q - UTF-8 string qstring* h - HTML text char * (only for GUI version; only for dynamic labels; no input) S - segment sel_t* N - hex number, C notation uval_t* n - signed hex number, C notation sval_t* L - C notation number uint64* (prefix 0x - hex, 0 - octal, otherwise decimal) l - same as L but with optional sign int64* M - hex number, no "0x" prefix uval_t* D - decimal number sval_t* O - octal number, C notation sval_t* Y - binary number, "0b" prefix sval_t* H - char value, C notation sval_t* $ - address ea_t* I - ident char* at least MAXNAMELEN size (obsolete, will be removed) i - ident qstring* B - button buttoncb_t* k - txt: button (same as B)/gui: hyperlink buttoncb_t* K - color button bgcolor_t* F - path to folder char* at least QMAXPATH size f - path to file char* at least QMAXPATH size T - type declaration char* at least MAXSTR size, obsolete, see below y - type declaration qstring* X - command char* at least MAXSTR size E - chooser chooser_base_t * - embedded chooser sizevec_t * - in/out: selected lines (0-based) (NB: this field takes two args) t - multi line text control textctrl_info_t * b - dropdown list qstrvec_t * - the list of items int* or qstring* - the preselected item (qstring* when the combo is editable, i.e. width field is >0)
The M, n, N, D, O, Y, H, $ fields try to parse the input as an IDC expression and convert the result into the required value type
If the buffer for 'F' field contains filemasks and descriptions like this: *.exe|Executable files,*.dll|Dll files they will be used in the dialog box filter.
The hint message can be specified before the label enclosed in '#':
<#hint message::label:...>
Radiobuttons and checkboxes are represented by:
<label:type> <label:type>> - end of block
where valid types are C and R (you may use lowercase 'c' and 'r' if you need to create two radiobutton or checkbox groups on the same lines). The field ID of the whole group can be specified between the brackets: <label:type>ID>
field types va_list parameter ----------- -----------------
C - checkbox ushort* bit mask of checkboxes R - radiobutton ushort* number of radiobutton
The box title and hint messages can be specified like this:
<#item hint::title::box hint::label:type>
The title and the box hint can be specified only in the first item of the box. If the hint doesn't exist, it should be specified as an empty hint (##title##) The subsequent items can have an item hint only:
<#item hint::label:type>
Initial values of input fields are specified in the corresponding input/output parameters (taken from va_list array).
OK, Cancel and (possibly) Help buttons are displayed at the bottom of the dialog box automatically. Their captions can be changed by the BUTTON keywords described at the beginning of this page.
Input field definition examples:
<Kernel analyzer options ~1~:B:0:::> <~A~nalysis enabled:C> <~I~ndicator enabled:C>> <Names pre~f~ix :A:15:15::> <~O~utput file:f:1:64::> <~O~utput directory:F::64::>
Resizable fields can be separated by splitter (GUI only) represented by <|> Splitter usage example: <~Chooser~:E1:0:40:::><|><~E~ditor:t2:0:40:::>
Functions | |
int | vask_form (const char *format, va_list va) |
See ask_form() | |
int | ask_form (const char *form,...) |
Display a dialog box and wait for the user. More... | |
TWidget * | vopen_form (const char *format, int flags, va_list va) |
Create and/or activate dockable modeless form (ui_open_form). More... | |
TWidget * | open_form (const char *form, int flags,...) |
Display a dockable modeless dialog box and return a handle to it. More... | |
Function Documentation
|
inline |
Display a dialog box and wait for the user.
If the form contains the "BUTTON NO <title>" keyword, then the return values are the same as in the ask_yn() function (Button IDs)
- Parameters
-
form dialog box as a string. see ask_form()/open_form()
- Return values
-
0 the user pressed Esc, no memory to display or form syntax error a dialog box (a warning is displayed in this case). all variables retain their original values. 1 ok, all input fields are filled and validated. -1 the form had BUTTON CANCEL and the user cancelled the dialog
|
inline |
Create and/or activate dockable modeless form (ui_open_form).
- Parameters
-
format string flags Widget open flags va args
- Returns
- pointer to resulting TWidget
|
inline |
Display a dockable modeless dialog box and return a handle to it.
- Parameters
-
form dialog box as a string. see ask_form()/open_form() flags Widget open flags
- Returns
- handle to the form or NULL. the handle can be used with TWidget functions: close_widget()/activate_widget()/etc
Generated by
