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

AUTOSYNC

  This will cause all fields to be updated with their current
  input value at the time CB_YES is called. This lets the callback
  (if provided) possibly perform validation of fields directly from
  their storage location, without having to query for their values
  individually.

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)

@hlpMessageName[]

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

              
char *string = "something";
ea_t addr = someaddr;
uval_t answer = 0;
int ok = ask_form(format, string, &addr, &answer);



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. It corresponds to the first variadic
argument regardless of its exact position in the format string.

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:@hlp[]>

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 - decimal number specifying the maximum possible number of
              characters that can be entered into the input field
              for X: decimal number specifying size of the buffer
                of characters that can be entered into the input field
                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
              for f, F: buffer is assumed to be at least QMAXPATH long
              for b (combobox) this attribute specifies the readonly attribute:
                0   - read-only combobox
                > 0 - editable combobox
              for n, N, D, O, Y, H, M, m: the width can have a '+' prefix.
                in this case, if the entered value starts with '+' or '-'
                sign, it will be added to or subtracted from the initial
                value. the caller will receive the result of this operation.
                the relative offset is always decimal.
      swidth -decimal number specifying width of visible part of input field
              this number may be omitted.
              for E, t: decimal number specifying the width of the input area.
                for these types the number cannot be omitted.
                note that the height is calculated automatically
      @hlp[]- 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
-----------------                               -----------------

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, "0x" prefix                     uval_t*
n - signed hex number, "0x" prefix              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*
m - same as M but for uint64                    ::uint64*
u - unsigned decimal number                     uval_t*
D - decimal number                              sval_t*
O - octal number, "O" prefix                    sval_t*
o - signed octal number, "O" prefix             sval_t*
Y - binary number, "0b" prefix                  sval_t*
s - signed binary number, "0b" prefix           sval_t*
H - char value, C notation                      sval_t*
$ - address                                     ::ea_t*
i - identifier (register names are forbidden)   qstring*
I - identifier (register names are permitted)   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
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)
                                                  selected rows are saved to this array
                                                  for modal forms only
                                                  (NB: this field takes two args)
t - multi line text control                     textctrl_info_t *
b - combobox (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)
p - UTF-8 string                                qstring* - echoed as a password field (i.e., with '*' masks)

The M, n, N, u, D, O, o, Y, s, 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 group box title and hint messages can be specified like this:

<#item hint[#group box title[#group box hint]]#label:type>

The group box title and the group box hint can be specified only in the
first item of the box. If the item 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  :q:15:15::>
 <~O~utput file:f:1:64::>
 <~O~utput directory:F::64::>

Resizable fields can be separated by splitters (GUI only).

A vertical splitter is represented by <|>. E.g.,:
  <~Chooser~:E1:0:40:::><|><~E~ditor:t2:0:40:::>
whereas a horizontal splitter is represented by <->. E.g.,:
  <~Chooser~:E1:0:40:::>
  <->
  <~E~ditor:t2:0:40:::>

It's also possible to organize fields by tabs (GUI only),
by adding a: <=:tab_label> after a series of fields. E.g.,:

  <This is a checkbox:c>>
  <=:Tab with a checkbox>
  
  <=:Tab with numeric input>100>

(where the field ID for the tabbed widget is: 100)

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, uint32 flags, va_list va)
	Create and/or activate dockable modeless form (ui_open_form). More...
TWidget *	open_form (const char *form, uint32 flags,...)
	Display a dockable modeless dialog box and return a handle to it. More...

Function Documentation

ask_form()

int ask_form ( const char *  form,   ...  )

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	no memory to display or form syntax error (a warning is displayed in this case). the user pressed the 'No' button (if the form has it) or the user cancelled the dialog otherwise. all variables retain their original values.
1	ok, all input fields are filled and validated.
-1	the form has the 'No' button and the user cancelled the dialog

vopen_form()

TWidget * vopen_form ( const char *  format, uint32  flags, va_list  va  )

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

open_form()

TWidget * open_form ( const char *  form, uint32  flags,   ...  )

inline

Display a dockable modeless dialog box and return a handle to it.

The modeless form can be closed in the following ways:

• by pressing the small 'x' in the window title
• by calling form_actions_t::close() from the form callback (form_actions_t)

  Note

  pressing the 'Yes/No/Cancel' buttons does not close the modeless form, except if the form callback explicitly calls close().

  Parameters

  form	dialog box as a string. see ask_form()/open_form()
  flags	Widget open flags

  Returns

  handle to the form or nullptr. the handle can be used with TWidget functions: close_widget()/activate_widget()/etc