/// <summary>
/// Stores the specified UI element properties in this object.
/// Parameters are like of <see cref="this"/>.
/// </summary>
/// <inheritdoc cref="this" path="/param"/>
public elmFinder(string role = null,
[ParamString(PSFormat.Wildex)] string name = null,
Strings prop = default, EFFlags flags = 0, Func <elm, bool> also = null,
int skip = 0, string navig = null
)
{
_role = role;
_name = name;
_prop = prop.Value switch { null => null, string s => s.Replace('|', '\0'), _ => string.Join('\0', prop.ToArray()) };
_flags = flags;
_also = also;
_skip = skip >= -1 ? skip : throw new ArgumentOutOfRangeException(nameof(skip));
_navig = navig;
}
public Cpp_AccFindParams(string role, string name, string prop, EFFlags flags, int skip, char resultProp) : this()
{
if (role != null)
{
_role = role; _roleLength = role.Length;
}
if (name != null)
{
_name = name; _nameLength = name.Length;
}
if (prop != null)
{
_prop = prop; _propLength = prop.Length;
}
this.flags = flags;
this.skip = skip;
_resultProp = resultProp;
}
/// <summary>
/// Creates an <see cref="elmFinder"/> for finding a UI element. Supports path like <c>var e = w.Elm["ROLE1", "Name1"]["ROLE2", "Name2"].Find();</c>.
/// </summary>
/// <returns>The new finder or the first finder in path.</returns>
/// <param name="role">
/// UI element role (<see cref="elm.Role"/>), like <c>"LINK"</c>.
/// Can have prefix <c>"web:"</c>, <c>"firefox:"</c> or <c>"chrome:"</c> which means "search only in web page" and enables Chrome UI elements.
/// Case-sensitive. Not wildcard. null means 'can be any'. Cannot be "".
/// More info in Remarks.
/// </param>
/// <param name="name">
/// UI element name (<see cref="elm.Name"/>).
/// String format: [](xref:wildcard_expression).
/// null means 'any'. "" means 'empty or unavailable'.
/// </param>
/// <param name="prop">
/// Other UI element properties and search settings.
/// Examples: <c>"value=xxx|@href=yyy"</c>, <c>new("value=xxx", "@href=yyy")</c>.
/// More info in Remarks.
/// </param>
/// <param name="flags"></param>
/// <param name="also">
/// Callback function. Called for each matching UI element. Let it return true if this is the wanted UI element.
/// Example: the UI element must contain point x y: <c>o => o.GetRect(out var r, o.WndTopLevel) && r.Contains(266, 33)</c>
/// </param>
/// <param name="skip">
/// 0-based index of matching UI element to use. Will skip this number of matching elements.
/// Value -1 means "any", and can be useful when this finder is intermediate (ie not the last) in a path or when it has <i>navig</i>. If intermediate, will search for next element in all matching intermediate elements. If has <i>navig</i>, will retry with other matching elements if fails to navigate in the first found. It is slower and not so often useful, therefore the default value of this parameter is 0, not -1.
/// </param>
/// <param name="navig">If not null, after finding the specified UI element will call <see cref="elm.Navigate"/> with this string and use its result instead of the found element.</param>
/// <exception cref="ArgumentException"><i>flags</i> contains <b>UIA</b> or <b>ClientArea</b> when appending (only the first finder can have these flags).</exception>
/// <remarks>
/// To create code for this function, use dialog "Find UI element".
///
/// In wildcard expressions supports PCRE regular expressions (prefix <c>"**r "</c>) but not .NET regular expressions (prefix <c>"**R "</c>). They are similar.
///
/// When using path like <c>["ROLE1", "Name1"]["ROLE2", "Name2"]["ROLE3", "Name3"]</c>, multiple finders are linked like finder1 -> finder2 -> finder3, so that the chain of finders will find UI element specified by the last finder.
///
/// More info in <see cref="elm"/> topic.
///
/// ##### About the <i>role</i> parameter
///
/// Can be standard role (see <see cref="ERole"/>) like <c>"LINK"</c> or custom role like <c>"div"</c>. See <see cref="elm.Role"/>.
///
/// Can have a prefix:
/// - <c>"web:"</c> - search only in the visible web page, not in whole window. Example: <c>"web:LINK"</c>.\
/// Supports Firefox, Chrome, Internet Explorer (IE) and apps that use same code (Edge, Opera...). With other windows, searches in the first found visible UI element that has DOCUMENT role.\
/// Tip: To search only NOT in web pages, use <i>prop</i> <c>"notin=DOCUMENT"</c> (Chrome, Firefox) or <c>"notin=PANE"</c> (IE).
/// - <c>"firefox:"</c> - search only in the visible web page of Firefox or Firefox-based web browser. If w window class name starts with "Mozilla", can be used <c>"web:"</c> instead.
/// - <c>"chrome:"</c> - search only in the visible web page of Chrome or Chrome-based web browser. If w window class name starts with "Chrome", can be used <c>"web:"</c> instead.
///
/// <note>Chrome web page UI elements normally are disabled (don't exist). Use prefix <c>"web:"</c> or <c>"chrome:"</c> to enable.</note>
///
/// Prefix cannot be used:
/// - if <i>prop</i> contains <c>"id"</c> or <c>"class"</c>;
/// - with flags <b>UIA</b>, <b>ClientArea</b>;
/// - when searching in <b>elm</b>.
///
/// ##### About the <i>prop</i> parameter
///
/// Format: one or more <c>"name=value"</c> strings, like <c>new("key=xxx", "@href=yyy")</c> or <c>"key=xxx|@href=yyy"</c>. Names must match case. Values of most string properties are wildcard expressions.
///
/// - <c>"class"</c> - search only in child controls that have this class name (see <see cref="wnd.ClassName"/>).\
/// Cannot be used when searching in a UI element.
/// - <c>"id"</c> - search only in child controls that have this id (see <see cref="wnd.ControlId"/>). If the value is not a number - Windows Forms control name (see <see cref="wnd.NameWinforms"/>); case-sensitive, not wildcard.\
/// Cannot be used when searching in a UI element.
/// - <c>"value"</c> - <see cref="elm.Value"/>.
/// - <c>"desc"</c> - <see cref="elm.Description"/>.
/// - <c>"state"</c> - <see cref="elm.State"/>. List of states the UI element must have and/or not have.\
/// Example: <c>"state=CHECKED, FOCUSABLE, !DISABLED"</c>.\
/// Example: <c>"state=0x100010, !0x1"</c>.\
/// Will find UI element that has all states without <c>"!"</c> prefix and does not have any of states with <c>"!"</c> prefix.
/// - <c>"rect"</c> - <see cref="elm.GetRect(out RECT, bool)"/> with <i>raw</i> true. Can be specified left, top, width and/or height, using <see cref="RECT.ToString"/> format.\
/// Example: <c>"rect={L=1155 T=1182 W=132 H=13}"</c>.
/// Example: <c>"rect={W=132 T=1182}"</c>.
/// The L T coordinates are relative to the primary screen.
/// - <c>"level"</c> - level (see <see cref="elm.Level"/>) at which the UI element can be found. Can be exact level, or minimal and maximal level separated by space.\
/// The default value is 0 1000.
/// - <c>"item"</c> - <see cref="elm.Item"/>.
/// - <c>"action"</c> - <see cref="elm.DefaultAction"/>.
/// - <c>"key"</c> - <see cref="elm.KeyboardShortcut"/>.
/// - <c>"help"</c> - <see cref="elm.Help"/>.
/// - <c>"uiaid"</c> - <see cref="elm.UiaId"/>.
/// - <c>"maxcc"</c> - when searching, skip children of UI elements that have more than this number of direct children. Default 10000, min 1, max 1000000.\
/// It can make faster. It also prevents hanging or crashing when a UI element in the UI element tree has large number of children. For example OpenOffice Calc TABLE has one billion children.
/// - <c>"notin"</c> - when searching, skip children of UI elements that have these roles. It can make faster.\
/// Example: <c>"notin=TREE,LIST,TOOLBAR"</c>.\
/// Roles in the list must be separated with <c>","</c> or <c>", "</c>. Case-sensitive, not wildcard. See also: <see cref="EFFlags.MenuToo"/>.
/// - <c>"@attr"</c> - <see cref="elm.HtmlAttribute"/>. Here "attr" is any attribute name. Example: <c>"@href=example"</c>.
/// </remarks>
/// <seealso cref="elm.path"/>
/// <seealso cref="Next"/>
public elmFinder this[string role = null,
[ParamString(PSFormat.Wildex)] string name = null,
Strings prop = default, EFFlags flags = 0, Func <elm, bool> also = null,
int skip = 0, string navig = null
] {
get {
var f = new elmFinder(role, name, prop, flags, also, skip, navig);
if (_flags == _EFFlags_Empty)
{
f._wnd = _wnd; f._elm = _elm; return(f);
}
var n = this; while (n._next != null)
{
n = n._next;
}
n.Next = f;
return(this);
}
}
internal elmFinder(wnd w, elm e)
{
_wnd = w;
_elm = e;
_flags = _EFFlags_Empty;
}
