Ragnar-F
commented
11 months ago Correct me if I'm wrong, but this looks like a summary created by an AI.
The main reason why this is perceived as clearer by some is the reduced information content. However, in technical documentation, such information cannot simply be omitted, but can at least be structured differently. For example, the options can be moved to a separate section (similar to v1), including a table of contents, but in my opinion this is not really worthwhile with the current amount of text.
It is already itemized by the use of paragraphs (1 paragraph per option) and the bold highlighting of the option name. A common way of presenting parameter values throughout the docs. The nested use of formatting that moves text to the right (e.g. bullets) should be avoided in favor of the mobile view of the docs. The further text is moved to the right, the harder it is to display on a small-screen mobile device. By the way, using numbers instead of bullets in "Supported Options" makes no sense.
For these reasons, it would be better to leave it as it is.
TLDR; Proposed improvements to the 'GuiControls' in the'GUiObject' page concept of Relative Sizing and Positioning.
Preamble: AHK is the reason I switched careers to developer 5 years ago, just want to say thanks.
I'm going through some of the documentation to attempt to help with one section if possible.
Nothing I say is a critique, I think ahkv2 is a mammoth accomplishment, I want to hopefully suggest where I see a different structure helping some people. Hopefully that makes sense.
One section that is abstract in concept but necessary for good code, the "Options" section of GuiObject, and more specifically Relative Sizing and Positioning as a concept. https://www.autohotkey.com/docs/v2/lib/Gui.htm#Methods
Relative sizing being a big improvement on the original relative tools. This may not be ubiquitous but I personally learn better with bullet points and itemized information. I also personally had a tough time understanding this section until consulting someone more educated on the matter.
I have attempted to bridge both verbose instruction and bullet point instruction, and some personal choices on phrasing to hopefully improve the section.
Only challenge is converting markdown to html, but none the less your feedback is paramount as to whether you would even accept a pull request for this section.
Cheers.
Note: My main focus was around the numbers on the Supported Options or Sizing section. I continued through the rest of that section for completeness but don't have as much critique for the "Storing and Responding to User Input" section of the original documentation.
AutoHotkey v2.0 GuiObject - Options ======================================= https://www.autohotkey.com/docs/v2/lib/Gui.htm#Methods
Supported Options
Rn: Specifies the number of rows of text, where "n" can be any number, including floating-point values (e.g., "r2.5"). R is often preferred over specifying H (Height). If both R and H options are present, R takes precedence. For GroupBoxes, it reserves space for controls inside the box. For certain controls like DropDownLists, ComboBoxes, and ListBoxes, it determines the number of visible items. For other controls, R represents the number of visible rows of text.
Wn: Defines the width of the control in pixels. If omitted, the width is calculated automatically based on the content. Different controls have default width calculations, such as tab controls, Progress Bars, and Sliders.
Hn: Sets the height of the control in pixels. If H and R options are absent, defaults apply based on the control type. For some controls like DropDownLists and ComboBoxes, H represents the combined height of the control's visible portion and list portion.
WP±n, HP±n: These options set the width and/or height of a control equal to the previously added control's width or height, with an optional plus or minus adjustment.
Xn, Yn: Define the X and Y positions of the control in pixels. For example, "x0 y0" positions the control in the upper left corner of the window's client area.
X+n, Y+n: Use the plus sign to position a control relative to the right or bottom edge of the previously added control. For example, "y+10" positions the control 10 pixels beneath the previous one.
X+ and Y+: These options use the letter M as a substitute for the window's current margin. For example, "x+m" positions the control using the right edge of the previous control plus the standard padding distance.
XP±n, YP±n: Position controls relative to the previous control's upper left corner, often useful for enclosing controls in a GroupBox.
XM±n, YM±n: Position a control at the leftmost and topmost margins of the window, with an optional plus or minus adjustment.
XS±n, YS±n: Similar to XM and YM, these options refer to coordinates saved by adding a control with the word "Section" in its options. They allow for organized control placement.
Omitting either X, Y, or both can make the GUI layout automatically adjust to changes in control size or font, ensuring that your controls are properly positioned.
If both X and Y are omitted, the control will be positioned beneath the previous control with standard padding.
Storing and Responding to User Input
To manage user input and identify controls, use the following options:
V: Sets the control's Name. Specify the name immediately after the letter V (e.g., "vMyEdit" would name the control "MyEdit").
Events: Event handlers cannot be set within the control's Options. Instead, use OnEvent to register callback functions or methods for each event of interest.
Common Options and Styles for Controls
Common options and styles include:
AltSubmit: Changes the behavior of certain controls regarding Gui.Submit.
C: Specifies the color of text.
Disabled: Makes a control appear disabled, preventing user interaction.
Hidden: Sets the initial visibility of the control.
Left, Right, Center: Text alignment options.
Section: Starts a new section for organized control placement.
Tabstop: Determines whether a control can be reached using the Tab key.
Wrap: Controls word-wrapping of content.
VScroll, HScroll: Enable vertical and horizontal scroll bars when necessary.
Uncommon Options and Styles for Controls
Uncommon options and styles include:
BackgroundTrans: Uses a transparent background.
BackgroundColor: Changes the background color of the control.
Border: Provides a thin-line border around the control.
Redraw: Enables or disables redraw (visual updates) for a control.
Theme: Overrides the window's current theme setting for the control.
Unnamed Style and ExStyle: Specify custom style and extended style options.
Please note that a plus sign is assumed in the absence of a preceding sign for many options. For instance, "Wrap" is equivalent to "+Wrap."