File MIES_GuiUtilities.ipf¶

Helper functions related to GUI controls.

Unnamed Group

variable PointsToPixel(variable var)¶: Conversion between pixel <-> points.

variable PixelToPoints(variable var)¶

Functions

variable ShowControl(string win, string control)¶: Show a GUI control in the given window.

variable ShowControls(string win, string controlList)¶: Show a list of GUI controls in the given window.

variable HideControl(string win, string control)¶: Hide a GUI control in the given window.

variable HideControls(string win, string controlList)¶: Hide a list of GUI controls in the given window.

variable EnableControl(string win, string control)¶: Enable a GUI control in the given window.

variable EnableControls(string win, string controlList)¶: Enable a list of GUI controls in the given window.

variable DisableControl(string win, string control)¶: Disable a GUI control in the given window.

variable DisableControls(string win, string controlList)¶: Disable a list of GUI controls in the given window.

variable SetControlTitles(string win, string controlList, string controlTitleList)¶: Set the title of a list of controls.

variable SetControlTitle(string win, string controlName, string newTitle)¶: Set the title of a control.

variable SetControlProcedures(string win, string controlList, string newProcedure)¶: Set the procedure of a list of controls.

variable SetControlProcedure(string win, string controlName, string newProcedure)¶: Set the procedure of a control.

string GetTitle(string recMacro, variable supress = defaultValue)¶

Return the title of a control.

Parameters:

recMacro – recreation macro for ctrl
supress – supress assertion that ctrl must have a title

Returns:

Returns the title or an empty string

variable SetControlTitleColors(string win, string controlList, variable R, variable G, variable B)¶: Change color of the title of mulitple controls.

variable SetControlTitleColor(string win, string controlName, variable R, variable G, variable B)¶: Change color of a control.

variable ChangeControlColor(string win, string controlName, variable R, variable G, variable B)¶: Change color of a control.

variable ChangeControlValueColor(string win, string controlName, variable R, variable G, variable B)¶: Change the font color of a control.

variable ChangeControlValueColors(string win, string controlList, variable R, variable G, variable B)¶: Change the font color of a list of controls.

variable SetControlBckgColor(string win, string controlName, variable R, variable G, variable B, variable Alpha = defaultValue)¶

Changes the background color of a control.

Parameters:

win – panel
controlName – GUI control name
R – red
G – green
B – blue
Alpha – defaults to opaque if not provided

variable ChangeControlBckgColors(string win, string controlList, variable R, variable G, variable B)¶: Change the background color of a list of controls.

variable GetCheckBoxState(string win, string control)¶: Returns one if the checkbox is selected or zero if it is unselected.

variable SetSetVariable(string win, string Control, variable newValue, variable respectLimits = defaultValue)¶: Set the internal number in a setvariable control.

variable SetSetVariableString(string win, string control, string str, variable setHelp = defaultValue)¶

Set the SetVariable contents as string.

Parameters:

win – window
control – control of type SetVariable
str – string to set
setHelp – [optional, defaults to false] set the help string as well. Allows to work around long text in small controls.

variable SetCheckBoxState(string win, string control, variable state)¶: Set the state of the checkbox.

variable SetSetVariableLimits(string win, string Control, variable low, variable high, variable increment)¶: Set the input limits for a setVariable control.

variable GetSetVariable(string win, string control)¶

Returns the contents of a SetVariable.

UTF_NOINSTRUMENTATION

string GetSetVariableString(string win, string control)¶: Returns the contents of a SetVariable with an internal string.

string GetPopupMenuString(string win, string control)¶: Returns the current PopupMenu item as string.

variable GetPopupMenuIndex(string win, string control)¶: Returns the zero-based index of a PopupMenu.

variable SetPopupMenuIndex(string win, string control, variable index)¶: Sets the zero-based index of the PopupMenu.

variable SetPopupMenuVal(string win, string control, string list = defaultValue, string func = defaultValue)¶: Sets the popupmenu value.

string SetPopupMenuString(string win, string control, string str)¶

Sets the popupmenu string.

Parameters:

win – target window
control – target control
str – popupmenu string to select. Supports wildcard character(*)

Returns:

set string with wildcard expanded

string GetValDisplayAsString(string win, string control)¶: Returns the contents of a ValDisplay.

variable GetValDisplayAsNum(string win, string control)¶: Returns the contents of a ValDisplay as a number.

variable GetSliderPositionIndex(string win, string control)¶: Returns the slider position.

variable SetSliderPositionIndex(string win, string control, variable index)¶: Sets the slider position.

variable SetValDisplay(string win, string control, variable var = defaultValue, string str = defaultValue, string format = defaultValue)¶

Set a ValDisplay.

The following parameter combinations are valid:

var
var and format
str

Parameters:

win – panel
control – GUI control
var – numeric variable to set
format – format string referencing the numeric variable var
str – path to global variable or wave element

variable ControlExists(string win, string control)¶: Check if a given control exists.

string FindControl(string control)¶: Return the full subwindow path to the windows the control belongs to.

string FindNotebook(string nb)¶: Return the full subwindow path to the given notebook.

variable GetTabID(string win, string ctrl)¶

Returns the number of the current tab.

Parameters:

win – window name
ctrl – name of the control

variable SetControlUserData(string win, string control, string key, string value)¶

Set value as the user data named key.

Parameters:

win – window name
control – name of the control
key – user data identifier
value – user data value

std::tuple<RGBColor> GetTraceColor(variable index)¶

Get distinctive trace colors for a given index.

Holds 21 different trace colors, code originally from http://www.igorexchange.com/node/6532 but completely rewritten and bug-fixed.

The colors are “Twenty two colors of maximum contrast” by L. Kelly, see http://www.iscc.org/pdf/PC54_1724_001.pdf, where the color white has been removed.

std::tuple<RGBColor> GetTraceColorForAverage()¶: Returns the trace color used for avergae type traces.

std::tuple<RGBColor> GetTraceColorAlternative(variable index)¶

Get colors from alternative color scheme.

Uses 8 colors with maximum contrast for colorblind people, see https://www.wavemetrics.com/code-snippet/distinguishable-color-index and https:// jfly.iam.u-tokyo.ac.jp/color/

See also

GetTraceColor

std::tuple<variable, variable> GetAxisRange(string graph, string axis, variable mode = defaultValue)¶

Query the axis minimum and maximum values.

For none existing graph or axis NaN is returned for minimum and high.

The return value for autoscale axis depends on the mode flag: AXIS_RANGE_INC_AUTOSCALED -> [0, 0] AXIS_RANGE_DEFAULT -> [NaN, NaN]

Parameters:

graph – [in] graph name
axis – [in] axis name
mode – [in] [optional:default AXIS_RANGE_DEFAULT] optional mode option, see AxisPropModeConstants

Returns:

minimum and maximum value of the axis range

static std::tuple<variable, variable> GetAxisRangeFromInfo(string graph, string info, string axis, variable mode)¶

variable GetAxisOrientation(string graph, string axes)¶

Return the orientation of the axis as numeric value.

Returns:: one of AxisOrientationConstants

static string GetAxisRecreationMacro(string info)¶: Return the recreation macro for an axis.

variable GetAxisLogMode(string graph, string axis)¶

Return the logmode of the axis.

Returns:: One of ModifyGraphLogModes

static variable GetAxisLogModeFromInfo(string info)¶

wave GetAxesProperties(string graph, string axesRegexp = defaultValue, variable orientation = defaultValue, variable mode = defaultValue)¶

Returns a wave with the minimum and maximum values of each axis.

Use SetAxesRanges to set the minimum and maximum values

See also

GetAxisRange

Parameters:

graph – [in] Name of graph
axesRegexp – [in] [optional: default not set] filter axes names list by this optional regular expression
orientation – [in] [optional: default not set] filter orientation of axes see AxisOrientationConstants
mode – [in] [optional: default AXIS_RANGE_DEFAULT] filter returned axis information by mode see AxisPropModeConstants

Returns:

free wave with rows = axes, cols = axes info, dimlabel of rows is axis name

variable SetAxesProperties(string graph, wave props, string axesRegexp = defaultValue, variable orientation = defaultValue, variable mode = defaultValue)¶

Set the properties of all axes as stored by GetAxesProperties.

Includes a heuristic if the name of the axis changed after GetAxesProperties. The axis range is also restored if its index in the sorted axis list and its orientation is the same.

See also

GetAxisProps

Parameters:

graph – [in] Name of graph
props – [in] wave with graph props as set in GetAxesProperties
axesRegexp – [in] [optional: default not set] filter axes names list by this optional regular expression
orientation – [in] [optional: default not set] filter orientation of axes see AxisOrientationConstants
mode – [in] [optional: default 0] axis set mode see AxisPropModeConstants

string GetNextFreeAxisName(string graph, string axesBaseName)¶: Returns the next axis name in a row of consecutive and already existing axis names.

string GetUniqueAxisName(string graph, string axesBaseName)¶: Return a unique axis name.

variable SetGuiControlValue(string win, string control, string value)¶: Generic wrapper for setting a control’s value pass in the value as a string, and then decide whether to change to a number based on the type of control.

string GetGuiControlValue(string win, string control)¶: Generic wrapper for getting a control’s value.

string GetGuiControlState(string win, string control)¶: Generic wrapper for getting a controls state (enabled, hidden, disabled)

variable SetGuiControlState(string win, string control, string controlState)¶: Generic wrapper for setting a controls state (enabled, hidden, disabled)

variable IsControlDisabled(string win, string control)¶: Return one if the given control is disabled, zero otherwise.

variable IsControlHidden(string win, string control)¶: Return one if the given control is hidden, zero otherwise.

string GetMainWindow(string subwindow)¶

Return the main window name from a full subwindow specification.

UTF_NOINSTRUMENTATION

Parameters:: subwindow – window name including subwindows, e.g. panel#subWin1#subWin2

string GetCurrentWindow()¶

Return the currently active window.

UTF_NOINSTRUMENTATION

wave GetCursorInfos(string graph)¶

Return a 1D text wave with all infos about the cursors.

Returns an invalid wave reference when no cursors are present. Counterpart to RestoreCursors().

The data is sorted like CURSOR_NAMES.

variable RestoreCursors(string graph, WaveTextOrNull cursorInfos)¶: Restore the cursors from the info of GetCursorInfos().

wave GetAnnotationInfo(string graph)¶: Return the infos for all annotations on the graph.

variable RestoreAnnotationPositions(string graph, WaveText annoInfo)¶: Restore annotation positions.

wave FilterAnnotations(WaveText annoInfo, string regexp)¶: Remove the annotations given by the regexp from annoInfo and return the filtered wave.

variable AutoscaleVertAxisVisXRange(string graph)¶: Autoscale all vertical axes in the visible x range.

variable GetInternalSetVariableType(string recMacro)¶

Return the type of the variable of the SetVariable control.

Returns:: one of GetInternalSetVariableTypeReturnTypes

variable ExtractLimitsFromRecMacro(string recMacro, variable *minVal, variable *maxVal, variable *incVal)¶

variable ExtractLimits(string win, string control, variable *minVal, variable *maxVal, variable *incVal)¶

Extract the limits specification of the control and return it in minVal, maxVal and incVal

See also

ExtractLimitsFromRecMacro for a faster way if you already have the recreation macro

Returns:: 0 on success, 1 if no specification could be found

variable CheckIfValueIsInsideLimits(string win, string control, variable val)¶

Check if the given value is inside the limits defined by the control.

Returns:

- 0: outside limits

1: inside limits, i.e. val lies in the range [min, max]
NaN: no limits could be found

variable GetLimitConstrainedSetVar(string recMacro, variable val)¶

Returns a value that is constrained by the limits defined by the control.

Returns:: val <= control max and val >= contorl min

variable GetFunctionParameterType(string func, variable paramIndex)¶

Return the parameter type a function parameter.

Parameters:

func – name of the function
paramIndex – index of the parameter

string GetValueFromRecMacro(string key, string recMacro)¶

Return an entry from the given recreation macro.

The recreation macro of a single GUI control looks like:

PopupMenu popup_ctrl,pos={1.00,1.00},size={55.00,19.00},proc=PGCT_PopMenuProc
PopupMenu popup_ctrl,mode=1,popvalue="Entry1",value= #"\"Entry1;Entry2;Entry3\""

This function allows to extract key/value pairs from it.

Parameters:

key – non-empty string (must be followed by = in the recreation macro)
recMacro – GUI control recreation macro as returned by ControlInfo

variable SearchForInvalidControlProcs(string win, variable warnOnEmpty = defaultValue)¶

Search for invalid control procedures in the given panel or graph.

Searches recursively in all subwindows.

Parameters:

win – panel or graph
warnOnEmpty – [optional, default to false] print out controls which don’t have a control procedure but can have one.

Returns:

1 on error, 0 if everything is fine.

variable GetNumericSubType(string subType)¶: Convert the function subType names for GUI control procedures to a numeric value as used by ControlInfo

variable GetControlType(string win, string control)¶

Return the numeric control type.

Returns:: one of GUIControlTypes

variable DoesControlHaveInternalString(string recMacro)¶: Determines if control stores numeric or text data.

variable GetCheckBoxMode(string win, string checkBoxName)¶: Returns checkbox mode.

variable GetListBoxSelRow(string win, string ctrl)¶: Returns the selected row of the ListBox for some modes without selection waves.

variable SetListBoxSelection(string win, string ctrl, variable val, variable row, variable col = defaultValue)¶

Set the listbox selection.

Parameters:

win – panel
ctrl – control
val – One of ListBoxSelectionWaveFlags
row – row index
col – [optional, defaults to all columns] column index

variable IsInsideRect(Point *loc, RectF *r)¶: Check if the location loc is inside the rectangle r

variable GetControlCoordinates(string win, string ctrl, RectF *s)¶: Return the coordinates of the control borders relative to the top left corner in pixels.

string GetNotebookText(string win, variable mode = defaultValue)¶: Get the text (plain or formatted) from the notebook.

variable ReplaceNotebookText(string win, string text)¶: Replace the contents of the notebook.

variable AppendToNotebookText(string win, string text)¶: Append to a notebook.

variable NotebookSelectionAtEnd(string win)¶

Select the end in the given notebook.

The selection is the place where the user would naïvely enter new text.

wave GetUserdataKeys(string recMacro)¶

Retrieves named userdata keys from a recreation macro string.

Parameters:: recMacro – recreation macro string
Returns:: Textwave with all unqiue entries or $"" if nothing could be found.

string ControlTypeToName(variable ctrlType)¶

Converts an Igor control type number to control name.

Parameters:: ctrlType – ctrl type of Igor control
Returns:: Igor name of control type

variable Name2ControlType(string ctrlName)¶

Converts an Igor control name to control type number.

Parameters:: ctrlName – Name of Igor control
Returns:: Igor control type number

variable WindowTypeCanHaveChildren(string wName)¶

Checks if a certain window can act as valid host for subwindows developer note: The only integrated Igor function that does this is ChildWindowList. Though, ChildWindowList generates an RTE for non-valid windows, where this check function does not.

Parameters:: wName – window name that should be checked to be a valid host for subwindows
Returns:: 1 if window is a valid host, 0 otherwise

string GetAllWindows(string wName)¶

Recursively build a list of windows, including all child windows, starting with wName.

Parameters:: wName – parent window name to start with
Returns:: A string containing names of windows. This list is a semicolon separated list. It will include the window wName and all of its children and children of children, etc.

static variable GetAllWindowsImpl(string wName, string *windowList)¶

variable IsSubwindow(string win)¶

variable PanelIsType(string device, string typeTag)¶

Checks if a window is tagged as certain type.

See also

panelTags returns 1 if window is a DA_Ephys panel

Parameters:

device – [in] Window name to check
typeTag – [in] one of PANELTAG_* constants

variable ShowSetVariableLimitsSelectionPopup(WMSetVariableAction *sva)¶

Show a contextual popup menu which allows the user to change the set variable limit’s increment.

Expects the ctrl to have the named user data “DefaultIncrement”
Works only on right mouse click on the title or the value field, not the up/down arrow buttons

variable DrawScaleBar(string graph, variable x0, variable y0, variable x1, variable y1, string unit = defaultValue, variable drawLength = defaultValue, variable labelOffset = defaultValue, variable newlineBeforeUnit = defaultValue)¶

Draw a scale bar on a graph.

Parameters:

graph – graph
x0 – horizontal coordinate of first point
y0 – vertical coordinate of first point
x1 – horizontal coordinate of second point
y1 – vertical coordinate of second point
unit – [optional] data unit when drawing the label
drawLength – [optional, defaults to false] true/false for outputting the label
labelOffset – [optional] offset in current coordinates of the label
newlineBeforeUnit – [optional] Use a newline before the unit instead of a space

std::tuple<string, variable> ParsePopupMenuValue(string recMacro)¶

Return the value and type of the popupmenu list.

Return values:

value – extracted string with the contents of value from the recreation macro
type – popup menu list type, one of PopupMenuListTypes

string GetPopupMenuList(string value, variable type)¶

Return the popupmenu list entries.

Parameters:

value – String with a list or function (what you enter with PopupMenu value=#XXX)
type – One of PopupMenuListTypes

variable ShowTraceInfoTags()¶: Enable show trace info tags globally.

std::tuple<string, variable> GetRecreationMacroAndType(string win, string control)¶: Return the recreation macro and the type of the given control.

variable GetControlSettingVar(string recMacro, string setting, variable defValue = defaultValue)¶: Query a numeric GUI control property.

string GetControlSettingStr(string recMacro, string setting, string defValue = defaultValue)¶: Query a string GUI control property.

static std::tuple<string, variable> GetControlSettingImpl(string recMacro, string setting)¶

variable AdaptDependentControls(string win, string controls, variable restoreOnState, variable newMainState, variable mode)¶

Dependent on a control state set the state of a list of checkboxes.

newMainState: state of the main control after the user interaction, in an event handler typically the cba.checked value restoreOnState: If the newMainState is different from the restoreOnState then the states of the dependent checkboxes is saved. If the newMainState is the same as the restoreOnState then the states of the dependent checkboxes are restored mode: DEP_CTRLS_SAME or DEP_CTRLS_INVERT, defines if the dependent checkbox state follows the newMainState or the inverted newMainState

When the dependent checkboxes are in the dependent state they are disabled. Example: if checkbox A is on, then checkbox B must be on as well and if checkbox A is off, then any state of checkbox B is valid and if checkbox A is changed to off then the state of checkbox B when A was in the off state before should be restored. results in: newMainState -> CHECKBOX_SELECTED (when A is switched on, then B is also switched according to mode and gets disabled, as a dependent checkbox) mode -> DEP_CTRLS_SAME (A -> on then B -> on) restoreOnState -> CHECKBOX_UNSELECTED (A -> off then B gets independent and restored, A -> on then B gets dependent and B’s state saved)

Restore on State	Main new	Mode	Action on dependent checkboxes
ON	OFF	DEP_CTRLS_SAME	state saved, unchecked, disabled
ON	OFF	DEP_CTRLS_INVERT	state saved, checked, disabled
ON	ON	ignored	state restored, enabled
OFF	ON	DEP_CTRLS_SAME	state saved, checked, disabled
OFF	ON	DEP_CTRLS_INVERT	state saved, unchecked, disabled
OFF	OFF	ignored	state restored, enabled

variable ReflowNotebookText(string win)¶: Adjust the “Normal” ruler in the notebook so that all text is visible.

variable ColorNotebookKeywords(string win, string keyWord, variable r, variable g, variable b)¶: In a formatted notebook sets a location where keyWord appear to the given color.

std::tuple<variable, variable> GetMarqueeHelper(string axisName, variable kill = defaultValue, variable doAssert = defaultValue, variable horiz = defaultValue, variable vert = defaultValue, string *win = defaultValue)¶

Marquee helper.

Parameters:

axisName – [in] coordinate system to use for returned values
kill – [in] [optional, defaults to false] should the marquee be killed afterwards
doAssert – [in] [optional, defaults to true] ASSERT out if nothing can be returned
horiz – [in] [optional] direction to return, exactly one of horiz/vert must be defined
vert – [in] [optional] direction to return, exactly one of horiz/vert must be defined
win – [out] [optional] allows to query the window as returned by GetMarquee

Return values:

first – start of the range
last – end of the range

variable ResizeControlsSafe(WMWinHookStruct *s)¶

Wrapper for ResizeControlsHook which handles a free datafolder as CDF.

Todo:: reported as #5100 to WM

Variables

static const string USERDATA_PREFIX = "userdata("¶

static const string USERDATA_SUFFIX = ")"¶

static const double AXIS_MODE_NO_LOG = 0¶

File MIES_GuiUtilities.ipf¶

Table of Contents

Previous topic

Next topic