Editing mirc/custom windows

{{mirc title|Custom Windows}}
Prior to mIRC 5.5, '''Custom Windows''' was the main method for making a GUI (graphical user interface).

== Custom Windows ==
A custom window is just another window, like a channel window or a server window but with the added ability to control every aspect of it. The following commands allow you to modify, add, and change things in that custom window of yours.

== Window Components ==
A custom window has the ability to contain the following 3 components:

[[File:Window component.png|Custom Window]]

== Creating a window ==
Before you can do anything with a window, you must actually create it. All windows must have a name, their name must also start with the '@' symbol. The name can be anything as long as it doesn't contain spaces. Use the {{mIRC|/window}} command to create a window:

<syntaxhighlight lang="mirc">/window @<WindowName> [x y [w h]]</syntaxhighlight>

This will create a blank window containing only the chatbox. If you'd like to add the editbox you'd need to use the -e switch. Placing a number after the switch allows you to define what kind of editbox to be used: 0 - single line, 1 - multi-line editbox, 2 - auto editbox, 3 - default. A window can also be made to be detached from the main window using the -d switch.

<syntaxhighlight lang="mirc">/window -e[N] @<WindowName> [x y [w h]]</syntaxhighlight>

A size-listbox can also be added to the window using the -l switch. Adding a number after the 'l' will define the width (in characters) of the listbox.

<syntaxhighlight lang="mirc">/window -l[N] @<WindowName> [x y [w h]]</syntaxhighlight>

For example:

<syntaxhighlight lang="mirc">alias example {
  ; -d desktop window, -e editbox, (3 = auto), -l = side-editbox (20-char width)
  ; position (200,200) size 500x350
  window -de3l20 @example 200 200 500 350
}</syntaxhighlight>

The code above will create a desktop window with an editbox and a side-listbox.

== Text Operations ==
The following commands can be used to add, modify, delete, insert, or replace the lines in the chatbox or the side-listbox:

* '''Add a line''' - This command will simply add a line of text to the end of the window. The [color] is the color number for the line. The -n switch can be used to prevent from adding duplicates. The -i indents the line. <syntaxhighlight lang="mirc">/aline [-ni] [color] <@name> <text></syntaxhighlight>
* '''Delete a line''' - This command is used to delete the Nth line from the window. The N2 line can be specified to give a range of line ex: 4-7 will delete line 4, 5, 6, and 7. <syntaxhighlight lang="mirc">/dline [color] <@name> <N[-N2]></syntaxhighlight>
* '''Insert a line''' - This command allows you to add a line of text after the Nth line. The [color] is the color number for the line. The -n switch can be used to prevent from adding duplicates. The -i indents the line. <syntaxhighlight lang="mirc">/iline [-ni] [color] <@name> <N> <text></syntaxhighlight>
* '''Replace a line''' - This command is used to replace the Nth line of a window with another line. The [color] is the color number for the line. <syntaxhighlight lang="mirc">/rline [color] <@name> <N> <text></syntaxhighlight>
* '''Change color of a line''' - This command is used to change the color of the Nth line with the new [color]. The -m switch can be used to associate nickname color in side-listbox with the nickname in the chatbox. The -r switch can be used to reset the color back to default. <syntaxhighlight lang="mirc">/cline [-rm] [color] <@name> <N></syntaxhighlight>
* '''Select a line''' - This command is used to select the Nth line of window. The -p switch can be used to force the line of text to be wrapped if it's too long to fit on one line. -h highlights the window's icon (only if its minimized). -a can be used to add this line to the current selection and -s can be used to clear the current selection and select just this line. <syntaxhighlight lang="mirc">/sline [color] <@name> <N></syntaxhighlight>

== Customizing the window ==
The titlebar command can be used to change the window's title.

<syntaxhighlight lang="mirc">/titlebar @window <text></syntaxhighlight>
'''Please Note:''' this will not change the actual @window name, only its title. To change the actual window's name, use the rewin command:

<syntaxhighlight lang="mirc">/renwin <@oldname> <@newname> [topic]</syntaxhighlight>

== Custom Window's Menu ==
You can also create a customized right click menu for the window, this can be done using one of the two ways:

  <ol>
    <li>Plain text file (must be named "POPUP.TXT") which will contain the menu</li>
    <li>Coding the menu in the remote section</li>
  </ol>

The first option is using a popup file. This method is very much like the popups tab in the script editor. In the code below we will assume you are going with option 2, writing it in the remote section. If you choose to go with a popup file, you will need to omit the "menu" keyword from your code. The basic syntax is:

<syntaxhighlight lang="mirc">menu @windowName {
  <event>: {
    ;/commands
  }
  ;or
  <event>: /commands
}</syntaxhighlight>

There are 8 possible built-in events; however, only 3 of them pertain to regular custom windows (the rest can only be used in a {{mIRC|Picture Windows#Mouse Events|Picture Window}}.

* '''dclick''' - Triggers when a mouse has double clicked on the window.
* '''rclick''' - Triggers when a mouse right clicked on the window.
* '''lbclick''' - Triggers when an item from the side-listbox was clicked.

In addition to built-in events, you can also add your own custom menu items.  If you have built-in mouse events as well as custom menu items, the built-in events MUST be placed above the custom menu items. The basic syntax for the menu items is:

<syntaxhighlight lang="mirc">menu @windowName {
  item: {
    ;/commands
  }
  ;or
  item: /commands
}</syntaxhighlight>

Sub menus and sub items are possible by prefixing the sub menu item with a period. Additional periods will indicate sub-sub menus. For example:

<syntaxhighlight lang="mirc">menu @example {
  menu  
  .sub_item: echo -a sub item clicked!
  .sub_item2
  ..sub__sub_item: echo -a sub sub item clicked!
  .sub: echo -a another item!
  item2: echo -a main item 2.
}</syntaxhighlight>

will generate the following menu:

[[File:Custom win menu.png|Custom Window Menu]]

== Getting Info ==
There are a number of identifiers that can be used to retrieved information from a custom window.

The $window identifier can be used to retrieve window-specific information:

<syntaxhighlight lang="mirc">$window(@name | N )</syntaxhighlight>

Some of $window's more helpful properties are:

{| class="wikitable"
! Property !! Description
|-
| x, y, w, h || left, top, width, and height
|-
| dx, dy, dw, dh || left, top, width and height position relative to the desktop
|-
| state || Returns the window's state (minimized/maximized/hidden/normal)
|-
| title || Returns the window's title
|-
| font || Returns the window's font
|-
| fontsize || Returns the window's font size
|-
| ontop || Returns $true/$false if the window is set ontop
|-
| wid || Returns the window's ID
|-
| sbtext || Returns the switchbar button text
|-
| sbcolor || Returns the switchbar highlight color
|-
| sbstate || Returns the switchbar button state
|-
| tdbstate || Returns the treebar button state
|}

== Retrieving Text ==
You can retrieve a line of text from a custom window using the $line identifier:

<syntaxhighlight lang="mirc">$line(@windowName, N, T)</syntaxhighlight>

$lines returns the Nth line of text from a window. If N = 0, $lines returns the total number of lines in the window. If T = 1, the side-listbox will be used instead of the chatbox (default is 0).

You can also search the window for a line wild-matching a specific sequence.

<syntaxhighlight lang="mirc">$fline(@windowName, wildtext, N, T)</syntaxhighlight>

This will return the Nth line wild-matching a specific wildtext sequence. If T = 1, the side-listbox will be used instead of the chatbox (default is 0).

If a listbox is used, you can use the $sline identifier to retrieve the Nth selected text.

<syntaxhighlight lang="mirc">$sline(@windowName, N)[.ln]</syntaxhighlight>

If N = 0, the total number of selected lines is returned. If the .ln property is used, the line number will be returned instead of the actual text.

[[Category:mIRC|custom windows]]