## imgmirc v0.29beta User Manual

## 1. Features & changelog

imgmirc.dll is an add-on for mIRC with 3 main features:

- Perl-compatible regular expression (PCRE) highlighting, which is intended to be used mainly for mIRC highlighting under non-english locales (case-insensitive too). Look through the overview or learn how it works in more details.

  ### Note

  In this v0.29 BETA release, non-english highlighting is temporarily broken, when working with mIRC versions over 7.0. Also, due to unicode support in mIRC, internal highlighting pattern (so called `%hl_mainstr`) is now composed from 6 ASCII characters (which might cause spurious highlights, though rarely).

- Drawing smileys images over textual smileys, similar to trillian. Look through the overview , or learn how it works.

- Substituting custom quit messages upon mIRC closing, similar to bitchx. Look through the overview, or learn how it works.

Main changes made in imgmirc v0.29beta:

- mIRC 7.0 and 7.10 supported.

- Sources were refactored a little bit.

- No PCRE library version 8.10 is used.

- Since it's a BETA release, some features might be broken. Also, it was tested only on mIRC 7.10 and Windows 7 for now.

Main changes made in imgmirc v0.28s:

- mIRC 6.35 supported.

Main changes made in imgmirc v0.27s:

- mIRC 6.34 supported.

- Sources are now to be compiled with MSVC 2005.

Main changes made in imgmirc v0.26s:

- Sources are included in the distributive (sources were not changed since v0.26).

- Added "known issues" section into the manual, kind of a FAQ.

Main changes made in imgmirc v0.26:

- Bug related to managing tcp/ip packets during pcre highlighting fixed.

- Keep alive system changed, related mIRC timer removed.

Main changes made in imgmirc v0.25:

- Transparent smileys drawing implemented. Useful when mIRC windows have non-white (or non-monochromatic) background.

- GUI configuration dialog. All imgmirc tuning is performed now through dialog instead of manual editing of mIRC variables.

- PCRE library package now linked statically with imgmirc.dll (v0.21 used dynamic linking).

imgmirc v0.29beta was specifically tested to work with mIRC version 7.10 on Windows 7. It should work with other mIRC/Windows versions, except for Windows 95.

## 2. Regexp-powered highlighting

With imgmirc, your favorite native mIRC highlighting can be achieved for any perl-compatible regex pattern. Customization of patterns is done via manual editing of `'imgmirc/highlights.txt'` file. Each line (except the first one) of the file is a regexp pattern you want to be highlighted. Regular expressions support is implemented by PCRE library by Philip Hazel.

NOTE: On the format of imgmirc/highlights.txt file: the very first line should contain a number of patterns in the file because the file is parsed by a mIRC script.

For correct highlighting, each pattern must looks like this:

`^[^\xa]*?(foobar)[^\x1\xd]*`

where 'foobar' is the word you want to be highlighted. If you want several words to be highlighted, you can add one more line to the file (don't forget to increment the number in the first line), but it is recommended to simply modify an existing line in the following way:

`^[^\xa]*?(foobar|blah)[^\x1\xd]*`

If you want, for example, to case-insensitively highlight the word 'blah', use line like this:

`^[^\xa]*?(foobar|(?i)blah)[^\x1\xd]*`

Note `'(?i)'` used for case-insensitiveness. And so on.

NOTE: Run `'man perlre'` on any *NIX box to get great manual on perl-compatible regilar expressions.

List of patterns can be viewed in mIRC by invoking an alias command `'/im_hllist'`. You can switch regexp highlighting on and off in imgmirc configurator dialog.

### 2.1. How does PCRE highlighting work

imgmirc.dll is statically linked with the PCRE library package, written by Philip Hazel (see copyrights section), which allows it to perform PCRE highlighting. When a text message matching one of patterns is received by mIRC, imgmirc appends several special symbols to the end of the line to be highlighted, but hides these symbols from a screen later. Generally speaking, "several special symbols" are contents of mIRC variable `%hl_mainstr` set by imgmirc, total 3 symbols in length. Therefore, if you customize mIRC to highlight every `%hl_mainstr` occurence (i.e., add `"%hl_mainstr"` without quotations to the mIRC highlights list) through

`Options->Irc->Highlight`

, or (in mIRC 6.34 for example),

`Tools->Address Book->Highlight`

, and configure highlighting behaviour as you like to, you achieve native mIRC highlighting for your custom regexp pattern. The value of `%hl_mainstr` changes automatically every time imgmirc.dll is loaded by mIRC (read - every time mIRC starts).

NOTE: Such highlighting method has a drawback: every line in the log file which coressponds to a highlighted line in the mIRC will have the value of %hl_mainstr appended to the end. Usually it looks like strange symbols near the line end (in the log file only). For this cost achieved the highlighting which works just the same way as native mIRC highlighting does.

## 3. Graphical smileys over text

imgmirc.dll can draw graphical images for corresponding smileys over text, so the result looks similar to trillian.

NOTE: Smileys supplied with imgmirc package are kind of optimised for 'Courier New 14' font. Altough default smileys images work with another fonts/sizes too, it is possible to change images if you don't like how smileys looks (learn how).

List of smileys replacements can be viewed in mIRC by issuing an alias command `'/im_relist'` (looks pretty ugly btw, try and you'll understand why :). Again, you can turn off smileys feature through imgmirc configurator dialog.

There was a change in version v0.25 related to smileys drawing. I've noticed many people use non-white background in mIRC windows, and therefore smileys (by default painted on white background) looks ugly for them, revealing frames around smileys themselves. It is possible to workaround this problem by editing smileys images, but of course, nobody wants to deal with it. Moreover, it is not a solution at all in the case of using non-monochromatic background like some sort of a picture. So, imgmirc since v0.25 is able to draw transparent images. Transparent color for smileys is white RGB(255,255,255).

NOTE: Of course, transparent drawing works slightly slower than default non-transparent. So, if your background mIRC windows color is the same as that of the smileys images, better turn transparent option off. It can be done through imgmirc configurator dialog.

### 3.1. How does smileys replacement work

NOTE: Basic understanding of Perl-compatible regular expressions is required to alter configuration files discussed below.

There is a directory `'imgmirc/imgs'` created when imgmirc were installed. It contains bitmap images of smiles (`*.bmp` files) and a list of regexp patterns (`replacements.txt` file). Each regexp pattern is associated with an image to be drawn. Every line of that file must look like this:

`(blah)#image.bmp#0#0#20#20 optional_comment`

In this example, a fragment of `image.bmp` with coordinates `(0, 0)` and size `(20, 20)` is selected to be drawn over the text `'blah'` when it is about to appear on the screen. By altering `replacements.txt` file you can set up you own smileys list.

The pattern used above, `'(blah)'`, is actually a regexp pattern. For example, to replace `':-)'` smiley, we use this line (note backslashes and parentheses):

`(\:-?\))#3block.bmp#0#0#20#20 smile`

Actual text under the smiley image is replaced with spaces (in case of non-transparent drawing), or is not printed at all (in case of transparent drawing) to make sure it will not be cut out. If the text dimensions is too small for the smiley to fit, the image will be stretched down, but image will not be stretched to increase its dimensions, because it looks ugly then.

Font i'm used to use is Courier New 14, thus I get images for font of size 14 (btw, these are the trillian default images, and they look pretty cool). Also they look not very terrible even being stretched to fixedsys font :) Also, it's better to use monospacing font, because in the case of non-monospacing font the problem of modifying string in order to be sure every 'slot' will correctly fit every occured smiley seems to be too complicated. At least I'm too lazy to solve it :)

## 4. Custom quit messages

imgmirc can use random message from a pre-defined list as your 'quit reason' then you quit from IRC. No matter, how exactly you do the quit, by clicking on the 'close window' button, or by pressing 'alt+f4'. This option turned on/off through `'perform /im_allquit...'` checkbox in the imgmirc configurator dialog.

Next section explains how to modify custom messages set.

### 4.1. How does custom quit messaging work

Custom quit messages list is stored in a file `'imgmirc/quit_msgs.txt'`, each line of which contains quit message. Also there are some aliases in your mIRC (created by imgmirc setup) responsible to use randomly chosen from that file message as your "quit reason" message.

All these things are good, but so far there is nothing to do with imgmirc.dll itself. imgmirc comes into play then you press `'alt+f4'` in mIRC, or kill the mirc by pressing upper-right close button. In that case, alias `'im_allquit'` is executed by imgmirc.dll, causing a send of quit message (causing call of the `'im_quit'` alias, to be accurate) for every server you connected to, and after this, closing the mIRC.

If you want to perform such a substitution even when you quit by typing `'/quit'` in the edit box, you have to add another mIRC alias by hand (you can probably add aliases into mIRC by pressing `'alt-r'`, and going to `'aliases'` tab):

`quit im_quit $1-`

Note that `'im_quit'` alias is smart, i.e. then (if alias above is created) you type:

`/quit behold my glory!`

result will be quitting from current server:

`* slartibartfast (~zvold@zvold.aero) Quit (Quit: behold my glory!)`

But if you type:

`/quit`

result will be also quitting from currently active server only, but the quit message will be taken from your custom quit messages list (`imgmirc/quit_msgs.txt`).

## 5. imgmirc variables

imgmirc variables section was refashioned in v0.25 due to introducing of the graphical configurator UI, through which all former variables should be changed now. All `'%imgmirc_*'` variables (except for `%imgmirc_ver`, see below) have been combined into the single variable `%imgmirc_config`, which you shouldn't edit manually.

There are two other variables besides `%imgmirc_config`:

- `%hl_mainstr` - string variable containing special line generated every time imgmirc.dll loads and used for regexp highilghting.

  NOTE: you must add mIRC highlight on `%hl_mainstr` manually in order to make PCRE highlighting work.

- `%imgmirc_ver` - contains current imgmirc version, also being refreshed with every imgmirc.dll loading.

NOTE: It's better not to change these variables by hand, they are internal imgmirc variables.

## 6. How to set up imgmirc

1. Kill all mirc applications, if running any.

2. Unzip the following files from imgmirc.zip into your mirc directory, OR, if you're running mirc with option -r, into your custom directory:

   - If you have already installed previous version of imgmirc, extract all files except subdirectories 'imgmirc\' and 'src\' from this package in order to preserve your old settings, such as highlights, quit messages, and perhaps customized smileys images.

   - If it's a first time you're setting up imgmirc.dll, just extract everything from the archive except 'src\' directory.

3. Run mirc.exe.

4. If it's a first-time installation:

   1. Type `'/load -rs imgmirc.mrc'`. Answer 'Yes' in following menu.

   2. Customize options, checking check boxes ;)

   3. If you've enabled custom quit messages, edit `'imgmirc/quit_msgs.txt'` file. Read this section of the manual, then add mirc alias `'quit im_quit $1-'` if you want to).

   4. If you've enabled regexp highlighting, read this section of the manual, then edit `'imgmirc/highlights.txt'` file. Also edit highlighting options for `%hl_mainstr` to that you're used to.

## 7. How to configure imgmirc

imgmirc configurator dialog is started by an alias command:

`/im_config`

, or through mIRC menu:

`Commands->imgmirc config`

When imgmirc.dll is installed for the first time, the configurator GUI invoked automatically.

You can customize following options:

- Enable smileys replacement (was `%imgmirc_smiles` variable in v0.21), see graphical smileys over text section.

- Transparent smileys - pretty much self-explanatory. If not, read graphical smileys over text section.

- Enable PCRE highlighting support (was `%imgmirc_pcrehl` in v0.21), see regexp-powered highlighting section.

- Perform /im_allquit... (was `%imgmirc_quithook` in v0.21), see custom quit messages section.

- Alt-x minimizes mIRC (was `%imgmirc_kbdhook` in v0.21) - if not set, pressing `'alt-x'` won't minimize mIRC.

- Automatically load with mIRC (was `%imgmirc_load` in v0.21) - if this option is set, imgmirc.dll is loaded automatically when mIRC starts (better leave this option enabled, but just in case, you can always load imgmirc.dll manually by using `'/im_preload'` alias).

- Enable verbose mode (was `%imgmirc_verbose` in v0.21) - toggle verbose behaviour of imgmirc off/on (useful for debugging).

- Protect from unloading by mIRC (was `%imgmirc_keepalive` in v0.21) - if not set, mIRC will automatically unload imgmirc.dll if it's not used for ten minutes (term 'not used' means no dll functions are called. Drawing of a smiley for example, is not a imgmirc.dll function call. So, better leave this check box set).

NOTE: Due to desired non-modality of configurator dialog, it's implementation appeared to be not very simple and uses a bunch of mIRC timers for synchronization. Shortly speaking, the probability of a bug in the configurator code is high, so any information on bugs found is much appreciated (for example, strange changes in check boxes status, or a failure to start the configurator dialog). Also, please read the known issues section.

## 8. Building from sources

imgmirc sources are located in the directory `'src'` in this distributive. imgmirc uses PCRE library, so the following files are needed to build the dll: `pcre.lib` (or `pcred.lib` for debug build) and `pcre.h`. I've included them in the distributive along with PCRE library license file `'license_pcre.txt'`. Starting from v0.27s, I build imgmirc.dll with MS Visual C++ 2005 compiler, project file `imgmirc.vcproj`. The process of building imgmirc.dll is hopefully like following: open `imgmirc.vcproj` file, and do `'rebuild all'` command for a "Release" configuration. You can also try to build using older imgmirc.dsp project.

Please NOTE that source code of imgmirc.dll is NOT in the public domain. This library is released under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. For more information, please read `lesser.txt` file provided within this package.

## 9. Known issues

- imgmirc doesn't work under Windows 95.

  And this will never be fixed probably. Techniques used in the imgmirc simply are not possible under Windows 95...

- imgmirc doesn't work in multiple instances of mIRC.

  imgmirc uses DDE for communicating with mIRC. When a second instance of mIRC is being started, it overrides previously created DDE server. There is always the single DDE server for all mIRC instances. That's why there is always only one imgmirc instance. Btw, mIRC supports multi-irc-server since version about 6.01, so I personally don't see any reason for multiple mIRC instances usage. If you use another mIRC instance for some kind of a bot, it's possible just to disable imgmirc in that instance, and enable it in your 'working' instance of mIRC.

  If one tries to run imgmirc on multiple instances of mIRC, results are kind of unpredictable.

- Smileys images can't be larger than 'enclosing' text.

  Several people asked how to make images larger while preserving remaining text in the original size. The answer is 'it's not possible'. imgmirc 'overrides' API function for text drawing, and draws images instead of letters. If images are larger than 'enclosing' letters, they either will overlap with other text, or become overlapped by it. It is impossible to 'slide apart' original text in order to fit large image between letters or lines. Hovewer, it would be easy to implement if mIRC starts using RichEdit as a base class for "chat" windows at some point in time.

  Actually, an issue with animated gif images goes to this section too. Because of images drawing system of imgmirc described above, it's not very easy (but it's possible) to track coordinates of images drawn in mIRC windows in order to update them at appropriate moments of time (e.g. animate).

- Transparent smileys sometimes overlap each other.

  This can be fixed and is in the TODO list.

## 10. Copyrights

- imgmirc.dll written by Ivan Zvolsky aka zvold (i.zvolsky@gmail.com). For licensing details, please refer to the 'Building from sources' section of this manual.

- Regular expression support is provided by the PCRE library package, which is open source software, written by Philip Hazel, and copyright by the University of Cambridge, England. ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/ See also http://pcre.org/

Thanks for reading, and sorry for spelling and grammar errors.