nHTMLn

by Necroman

 

 

Introduction

 

 

nHTMLn is a dynamic-link library (DLL) for mIRC. You can download version 2.5 from here. You need at least Internet Explorer 4.0 and mIRC 5.8 to use this DLL.

 

It allows you to display HTML pages from within the client. You can display modeless pages over any window, including, but not limited to: the status window, picture windows, dialogs, dialog controls, the MDI frame, and the desktop. The pages can contain graphics, music, scripts, Java applets, Flash movies, etc. – everything supported by Internet Explorer.

 

 

 

Features

 

·       Ability to attach up to 256 browsers per 1 instance of the DLL

·       19 functions to control behavior and appearance of browsers

·       Custom event model supporting 11 types of HTTP events

·       Experimental printing support

·       Small size (27,5kb)

·       Source code availability

 

 

Basics

 

 

1. As a scripter, you can create objects called “browsers” and attach them to your windows.

 

2. Once attached, a browser can be ordered to navigate to any HTML page, remote or local.

 

3. When you don’t need a browser anymore, call the ‘detach’ function and it will disappear.

 

 

 

nHTMLn functions

 

All the nHTMLn functions should be called as $dll(nHTMLn,name,argument)or (if you don’t need the return value) as dll nHTMLn name argument .

 

You are encouraged to create aliases to reduce typing, for example:

 

alias nn { var %dummy = $dll(nHTMLn,$$1,$iif($2 == $null,0,$2)) }

 

 

attach, detach

 

The ‘attach’ function creates a new browser and attaches it to a window. If the browser was created successfully, it is selected as the default browser for subsequent operations.

 

The ‘detach’ function detaches, hides and destroys a browser specified by the window handle in the input parameter. If the handle is invalid, the default browser gets detached.

 

Parameter:

 

The handle of the parent window.

 

Return values:

 

E_INVALID_WINDOW

E_FAILED

E_ALREADY_ATTACHED

E_TOO_MANY_BROWSERS

S_OK

 

Remarks:

 

An attached browser fills the client area of its parent (container) completely.

 

You cannot attach 2 browsers to the same window.

 

A browser is automatically detached when its parent window closes. This means your user can detach a

browser if he/she clicks on the X button.

 

If you attach a browser to a disabled dialog control, the user will not be able to scroll or follow hyperlinks (‘frozen HTML graphics’).

 

Examples:

 

The following lines attach and detach 2 browsers. Notice that in line 3 we specify an invalid window handle (0) and the command works on the default browser (attached to the window named @test).

 

window –p @test

echo –a $dll(nHTMLn,attach,$window(-3).hwnd)

echo –a $dll(nHTMLn,attach,$window(@test).hwnd)

echo –a $dll(nHTMLn,detach,0)

echo –a $dll(nHTMLn,detach,$window(-3).hwnd)

 

 

navigate

 

This function tells the default browser to display an HTML page.

 

Parameter:

 

The URL to navigate to.

 

Return values:

 

E_INVALID_WINDOW

E_FAILED

S_OK

 

Examples:

 

This code creates a browser and displays the mIRC homepage:

 

window –p @test

echo –a $dll(nHTMLn,attach,$window(@test).hwnd)

echo –a $dll(nHTMLn,navigate,www.mirc.com)

 

This code displays the mircscripts.org webboard on the desktop:

 

echo –a $dll(nHTMLn,attach,$window(-1).hwnd)

echo –a $dll(nHTMLn,navigate,www.mircscripts.org/board)

 

This code displays the Microsoft Word document in the mIRC MDI frame:

 

echo –a $dll(nHTMLn,attach,$window(-3).hwnd)

echo –a $dll(nHTMLn,navigate,d:\mirc\mytext.doc)

 

 

select

 

This function is used to set the default browser. The default browser is usually called when the window handle in the input parameter is invalid. However, the ‘navigate’ and ‘handler’ functions always use the default browser.

 

Parameter:

 

The handle of a window with a browser attached.

 

Return values:

 

E_INVALID_WINDOW

S_OK

 

Examples:

 

This code displays 2 HTML pages in 2 browsers.

 

echo –a $dll(nHTMLn,attach,$window(@test1).hwnd)

echo –a $dll(nHTMLn,attach,$window(@test2).hwnd)

echo –a $dll(nHTMLn,navigate,www.location2.com)

echo –a $dll(nHTMLn,select,$window(@test1).hwnd)

echo –a $dll(nHTMLn,navigate,www.location1.com)

 

Often, the ‘select’ function is not necessary. The previous example can be rewritten as follows:

 

echo –a $dll(nHTMLn,attach,$window(@test1).hwnd)

echo –a $dll(nHTMLn,navigate,www.location1.com)

echo –a $dll(nHTMLn,attach,$window(@test2).hwnd)

echo –a $dll(nHTMLn,navigate,www.location2.com)

 

selected

 

This function returns the handle of the default browser’s parent window.

 

Parameter:

 

None.

 

Return values:

 

The handle of the default browser’s parent window.

 

Remarks:

 

The returned handle may be invalid if the window has been closed.

 

If you use the ‘select’ function in your event-handling alias, make sure to restore the selection.

 

Examples:

 

This code navigates to www.wot.net/~necroman/nn2.htm without changing the currently selected browser:

 

var %old_hwnd = $dll(nHTMLn,selected,0)

window –p @test

echo –a $dll(nHTMLn,attach,$window(@test).hwnd)

echo –a $dll(nHTMLn,navigate,www.wot.net/~necroman/nn2.htm)

echo –a $dll(nHTMLn,select,%old_hwnd)

 

 

stop, refresh

 

The ‘stop’ function tells a browser to stop downloading its HTML page. The ‘refresh’ function forces reloading the page.

 

Parameter:

 

The handle of the window with a browser attached. If the handle is invalid, the default browser is used.

 

Return values:

 

E_INVALID_WINDOW

E_FAILED

S_OK

 

Examples:

 

echo –a $dll(nHTMLn,select,$window(@somewindow).hwnd)

echo –a $dll(nHTMLm,refresh,0)

echo –a $dll(nHTMLn,stop,0)

 

 

back, forward, home, search

 

These functions perform the same actions as the equivalent buttons in the Internet Explorer toolbar.

 

Parameter:

 

The handle of the window with a browser attached. If the handle is invalid, the default browser is used.

 

Return values:

 

E_INVALID_WINDOW

E_FAILED

S_OK

 

Examples:

 

window –p @test

echo –a $dll(nHTMLn,attach,$window(@test).hwnd)

echo –a $dll(nHTMLn,navigate,www.mirc.com)

echo –a $dll(nHTMLn,navigate,www.wot.net/~necroman/nn2.htm)

echo –a $dll(nHTMLn,back,0)

 

 

name, url

 

These functions return the name and URL of the HTML page currently displayed in a browser.

 

Parameter:

 

The handle of the window with a browser attached. If the handle is invalid, the default browser is used.

 

Return values:

 

The name or the URL of the currently displayed page.

E_INVALID_WINDOW

E_FAILED

 

Examples:

 

This code updates the titlebar of a picture window with the name of the currently loaded HTML page:

 

titlebar @test $dll(nHTMLn,name,$window(@test).hwnd)

 

 

find, caption

 

The ‘find’ function returns the handle of a window with a certain caption. The ‘caption’ function returns the caption of a window with a certain handle.

 

Parameter:

 

The text (‘find’) or handle (‘caption’) to search for.

 

Return values:

 

If the window is not found the return value is E_NOT_FOUND.

 

Remarks:

 

The ‘find’ function can be useful when you’re trying to attach a HTML page to one of the controls in your dialog. This function searches ALL windows on the desktop, not only mIRC children. To avoid collisions, make the caption of your dialog control unique and call the ‘find’ function. Once you have got the handle you can restore the original name of your control.

 

Examples:

 

This code obtains a window handle of your dialog control named “MyLameLabel” and attaches a browser to it:

 

var %hwnd = $dll(nHTML,find,MyLameLabel)

if (E* !iswm %hwnd) { echo –a $dll(nHTML,attach,%hwnd) }

 

 

handler

 

This function designates an event handler for the default browser.

 

Parameter:

 

The name of an alias, which will be called when an HTML event occurs.

 

Return values:

 

E_INVALID_WINDOW

S_OK

 

Remarks:

 

Several browsers can have the same handler.

 

The handle of the browser’s parent window is stored in parameter $1. Parameter $2 holds the name of the event:

 

 

$2

 

 

Meaning

 

navigate_begin

–   browser is about to navigate to a URL

state_change

–   state of “Back” and “Forward” buttons changes

navigate_complete

–   browser has navigated to a URL

document_complete

–   document has been downloaded

window_open

–   new Internet Explorer is about to open

download_begin

–   browser is about to start downloading

progress_change

–   download progress changes

download_complete

–   browser has finished downloading

status_change

–   status bar text has changed

title_change

–   titlebar text has changed

visibility_change

–   visibility has changed (untested)

 

Parameters $3- are event-specific.

 

Normally you should return S_OK from your handler. You can halt the ‘navigate_begin’ and ‘window_open’ events if you return S_CANCEL (it does not work for local folders, sorry). If you return anything but S_OK or S_CANCEL the browser stops firing events. To resume event processing, call the ‘handler’ function again.

 

If you use the ‘select’ function in your event-handling alias remember to restore the original selection (use the ‘selected’ function to obtain it).

 

An event handler should be as small and fast as possible. It must NOT:

 

X detach the browser that generated the event

X close its parent window

X unload the DLL

 

nHTMLn events are only fired under mIRC 5.9 and newer.

 

Examples:

 

This code attaches a browser to a window and sets the “nHTMLn.handler” as its event handler.

 

window –p @test

echo –a $dll(nHTMLn,attach.$window(@test).hwnd)

echo –a $dll(nHTMLn,handler,nHTMLn.handler)

 

alias nHTMLn.handler {

  echo –a browser = $dll(nHTMLn,caption,$1) 2-

  return S_OK

}

 

This code forbids opening new windows:

 

window –p @test

echo –a $dll(nHTMLn,attach,$window(@test).hwnd)

echo –a $dll(nHTMLn,handler,nHTMLn.handler)

echo –a $dll(nHTMLn,navigate,www.mircscripts.org/board)

 

alias nHTMLn.handler {

  if ($2 == new_window) { return S_CANCEL }

  return S_OK

}

 

 

This code makes the default browser stop firing events:

 

echo –a $dll(nHTMLn,handler,!)

 

 

print

 

This function prints a web page.

 

Parameter:

 

The handle of the window with a browser attached. If the handle is invalid, the currently selected browser is used.

 

Return values:

 

E_INVALID_WINDOW

E_FAILED

S_OK

 

Examples:

 

This code prints www.mirc.com:

 

window –pnh @test

echo –a $dll(nHTMLn,attach,$window(@test).hwnd)

echo –a $dll(nHTMLn,handler,myalias)

echo –a $dll(nHTMLn,navigate,www.mirc.com)

 

alias myalias {

  if ($2 == document_complete) {

    echo –a $dll(nHTMLn,print,$window(@test).hwnd)

    window –c @test

  }

  return S_OK

}

 

 

version

 

This function returns information about the DLL and its author.

 

Parameter:

 

None.

 

Example:

 

var %version = $gettok($dll(nHTMLn,version,0),2,32)

if (%version < 2.5) { echo –a wrong version of nHTMLn }

 

 

Frequently Asked Questions

 

 

Q: nHTMLn always echoes S_OK, how can I stop that?

 

A: It does not echo itself; it returns the error code. You are free to echo it, if you want, that’s the way I used it in the examples.

 

You can store the result into a dummy variable or use it some expression.

 

var %d = $dll(nHTMLn,navigate,www.microsoft.com)

or

if (S* iswm $dll(nHTMLn,navigate,www.microsoft.com)) { … }

 

Finally, you can use dll nHTMLn attach $window(-3).hwnd, but I do not recommend it.

 

 

Q: mIRC caret gets invisible sometimes, why is that?

 

A: Certain HTML pages, like www.google.com contain scripts that activate their windows and put the caret into their editboxes.

 

 

Q: Is it possible to get a list of all attached browsers?

 

A: This can easily be done with mIRC scripting.

 

 

Q: Why don’t the TAB and ENTER work in HTML edit boxes?

 

A: I don’t know.

 

 

Q: How to attach a browser to a dialog control?

 

A: Use the ‘find’ function to obtain the handle of the control and attach a browser it.

 

 

Q: What is the purpose of the DLL?

 

A: To provide mIRC scripters with richer GUI capabilities. For example, let your modal dialog display a background picture. If you are a JScript or VBScript writer, you can create your own GUI in HTML. If you are developing a full script, you can create a nice introduction to it with a Flash movie. If you’re making a help system, you can store the pages on your website and update them periodically.

 

 

Sincerely yours, Necroman.

 

#mIRC @ Undernet, necroman@wot.net

 

 

Home