Introduction
JSDraw.dll is an ActiveX DLL for use with VBScript. It enables drawing, writing of text
and placing of pictures directly on the screen. JSDraw could be used for scripted presentations,
program installations, or just for fun. It might provide an interesting means for inexperienced people
to learn scripting.
There are several drawing options available, including shapes, text and pictures. Drawing
to the screen in this way is temporary. Any window can be used as an "eraser" to update
the screen to original display. There is also a Refresh method that will erase all drawing, a
Capture method to save drawing as a BMP file, and several functions to enable custom message box windows.
To create the object:
Dim Ob
Set Ob = CreateObject("JSDraw.Ops")
Requirements:
Windows 98 or later. (jsDraw.dll may work on Win95 and WinNT 4 but has not been
tested on those systems.) The component must be registered before use.
To register the component, put JSDraw.dll in the System folder and then
drag/drop it onto the RegSvr.vbs script. Click YES to register. The object will then be ready for use.
jsDraw is a 32-bit DLL. On Windows 64-bit it should go in the SysWOW64 folder. Do not put it
in the System32 folder on Win64. (Unfortunately, Microsoft created a very confusing naming system for Win64.
On Win32, the 32-bit system folder is System32. But on Win64 the names have been reversed:
The 64-bit folder is System32 while the 32-bit folder is SysWOW64!)
Issues:
jsDraw.dll should work fine on all Windows versions, but there will be slight
variations in behavior. In particular, with graphics drawn to the screen. Graphics drawn to
the popup window are stable, while graphics drawn to the screen are not. They get erased
when the screen needs to update its display.
Later versions of
Windows have increasingly overproduced graphic effects. When graphics are drawn to the
screen in Windows 98 they tend to be fairly stable until a window is dragged over them,
because the display refresh only happens when actions are taken such as opening or moving
windows. On Windows 7 with Aero
one sees a very different scenario. Objects change when hovered over, buttons glow, etc.
As a result, Desktop items may "pop through" screen drawing immediately when drawn over
a window.
Back to Top
Property Color
• Get/Set default color for use with drawing methods.
ex: ob.Color = "FFFFFF"
It is not necessary to set default color. Each relevant method
has a color parameter. The default color is just a convenience
for use when the same color is used repeatedly. Using "" for
a method's color parameter will use the default color.
Default color before any is set is black ("000000").
Back to Top
Property Font
• Get/Set default font used for drawing text.
ex: ob.Font = "arial"
When text is drawn it will be drawn with last font set. If font
has not been set text will be drawn with MS Sans Serif. When
setting, if Font string is not an installed screen font it will not be set.
Back to Top
Method SetCanvas(Left, Top, Width, Height)
• Sets area where drawing will be done.
ex: ob.SetCanvas 100, 100, 300, 300
The default canvas is the entire screen. SetCanvas has 2 purposes:
1) To designate a screen area for drawing in order to simplify the computation
of coordinates. Once a call to SetCanvas is made all drawing will be relative to
the new coordinates. For example SetCanvas 100, 100, 300, 300 will designate
an area for drawing that is 300 x 300, inset from left by 100 and inset from
top by 100 (all coordinates are in pixels). If a line is then drawn starting at
0,0 that will be 0,0 in the canvas or 100,100 on the Desktop.
2) To control text placement. By setting a canvas just big enough for the
text used the placement of text can be controlled.
SetCanvas can be used at any time to designate a new drawing area. It does
not affect graphics previously drawn.
Back to Top
Method Refresh
• Erase all drawing.
ex: ob.Refresh
Back to Top
Function GetSystemColor(Item)
• Returns one of 5 system colors.
ex: v = ob.GetSystemColor("Desktop")
Item can be either a number or one of 5 strings :
0 or Desktop - returns Desktop back color.
1 or TitleBar - returns primary title bar back color.
2 or TitleBarText - returns title bar text color.
3 or Button - returns color of buttons and window objects.
4 or ButtonText - returns color of text on buttons.
Color is returned as 6-character hex code (RGB) such as "00FF00"
which can be used in drawing. If
Item is invalid "000000" is returned.
Back to Top
Function GetDesktopSize(Width, Height)
• Returns Desktop dimensions in pixels.
ex: Boo = ob.GetDesktopSize(w, h)
Boolean function - returns True on success.
Width returns Desktop width in pixels.
Height returns Desktop height in pixels.
Back to Top
Function GetPictureSize(FilePath, Width, Height)
• Returns graphic file dimensions in pixels.
ex: Boo = ob.GetPictureSize("C:\pic.bmp", w, h)
Boolean function - returns True on success, False if call
failed or if file not found.
FilePath is full path to image file. Image is processed as
a StdPicture object It can be ICO, BMP, or JPG.
Width returns image width in pixels.
Height returns image height in pixels.
Back to Top
Method Capture(FilePath, Left, Top, Width, Height)
• Saves a screen capture as BMP file.
ex: ob.Capture "C:\pic.bmp", 100, 100, 300, 400
FilePath is path of BMP file to be created.
Left, Top, Width, Height reference dimensions and location
of Desktop area to capture.
Capture saves all or part of the current screen image as a BMP file.
Use Left and Top for X,Y coordinates of topleft pixel in image.
For entire desktop use:
boo = ob.GetDesktopSize(w, h)
ob.Capture sFilePath, 0, 0, w, h
If FilePath does not end in ".bmp" then ".bmp" will be appended.
If FilePath exists Capture will not overwrite it.
The Capture method can be used to save a copy of graphics drawn onscreen.
Note: Capture is not a drawing method. The coordinates do not
correspond to the current canvas but rather to the Desktop. To capture
current drawing set parameters to canvas coordinates.
Back to Top
Method Fill(Color)
• Fills current canvas with a single color.
ex: ob.Fill "00FF00"
Color is any 6-character hex code.
Fill will color the current canvas. The current canvas is the
entire screen if SetCanvas has not been used.
Back to Top
Method Line(StartX, StartY, EndX, EndY, LineWidth, Color)
• Draws a line at coordinates relative to current canvas.
ex: ob.Line 100, 100, 400, 400, 4, "FF0000"
StartX, StartY are starting coordinates for line relative to current canvas.
EndX, EndY are end coordinates for line relative to current canvas.
LineWidth is thickness of line in pixels.
Color is line color as 6-char. hex code. Use "" to make line default color
that was set with Color Property.
Back to Top
Method Arc(BoxLeft, BoxTop, BoxWidth, BoxHeight, ArcStartX, ArcStartY, ArcEndX, ArcEndY, LineWidth, Color)
• Draws an arc at coordinates relative to current canvas.
ex: ob.Arc 140, 320, 20, 80, 140, 340, 160, 360, 5, "FF0000"
An Arc is a section of an ellipse.
BoxLeft, BoxTop, BoxWidth and BoxHeight define a rectangle
that represents the bounds of the ellipse. The arc is drawn starting where
ArcStartX, ArcStartY coordinates intersect an imaginary line drawn
from the center of the rectangle. The end of the arc is drawn where
ArcEndX, ArcEndY coordinates intersect an imaginary line drawn
from the center of the rectangle.
LineWidth is thickness of line in pixels.
Color is line color as 6-char. hex code. Use "" to make line default color
that was set with Color Property.
Back to Top
Method Rectangle(Left, Top, Width, Height, LineWidth, Color, IfFilled)
• Draws a rectangle at coordinates relative to current canvas.
ex: ob.Rectangle 100, 100, 400, 400, 0, "FF0000", True
Left, Top are coordinates of top left corner of rectangle.
Width is width and
Height is height of rectangle.
LineWidth is thickness of line in pixels.
Color is line color as 6-char. hex code. Use "" to make line default color
that was set with Color Property.
IfFilled - Boolean value. True to fill rectangle with color. False to outline.
If rectangle is filled LineWidth is ignored and can be 0.
Back to Top
Method Ellipse(Left, Top, Width, Height, LineWidth, Color, IfFilled)
• Draws an ellipse at coordinates relative to current canvas.
ex: ob.Ellipse 100, 100, 400, 400, 0, "FF0000", True
Left, Top are coordinates of top left corner of rectangle that bounds ellipse.
Width is width and
Height is height of rectangle that bounds ellipse.
LineWidth is thickness of line in pixels.
Color is line color as 6-char. hex code. Use "" to make line default color
that was set with Color Property.
IfFilled - Boolean value. True to fill ellipse with color. False to outline.
If ellipse is filled LineWidth is ignored and can be 0.
Back to Top
Method Picture(FilePath, Left, Top)
• Draws an image from a graphic file at coordinates relative to current canvas.
ex: ob.Picture "C:\pic.bmp" 100, 100
FilePath is full path to image file. Image is processed as
a StdPicture object which can be ICO, BMP, or JPG.
Left, Top are coordinates for placement of top left corner of picture.
Back to Top
Method Text(Text, FontWidth, FontHeight, TextColor, BackColor, IfCentered)
• Draws text in current canvas.
ex.: ob.Text "This is some text" 30, 60, "000000", "FFFFFF", True
Text is text to write, which can include VBCrLf.
FontWidth, FontHeight are width and height of characters.
TextColor is color of text. Use "" for default color previously
set with Color Property.
BackColor is color for background of text. Use "" for transparent background.
IfCentered - True for text centered in current canvas. False for left-aligned text.
Text is drawn with font set using Font Property. If no font is set MS Sans Serif is used.
Notes:
Controlling placement of text is done by setting the current canvas with SetCanvas.
If Canvas is not sufficiently large to hold text it may not properly draw in the area specified.
Back to Top
Overview of Popup Functions
The Popup functions are somewhat unusual. This section is provided to explain general usage.
The Popup window is a do-it-yourself message window. It's a blank, white window that can be
drawn on and then displayed. All of the JSDraw drawing functions can be used with the Popup window.
The single parameter of the Popup function, Seconds, allows the window to mimic both the MsgBox
and Popup functions from VBS. The window can receive click events from up to 4 defined hotspots
(rectangular areas of the window). When the function returns it contains 0 or the number of the
hotspot clicked. In that way, Popup can take user input through up to 4 buttons - and the "buttons"
can be whatever you like.
The
MakePopup and
CancelPopup functions are key to switching between screen
drawing and Popup functions. By default, all drawing functions are done on the screen. When
MakePopup
is called it sets the size and position of the Popup window; it also switches all drawing functions to
the Popup window.
MakePopup might be thought of as "Let's make a Popup". It does not show the
Popup window.
MakePopup is the first step. Once the window is displayed, or a call is made
to
CancelPopup, drawing functions revert to the Desktop.
Once
MakePopup has been called the current canvas is the Popup window and all calls
to
SetCanvas will work in relation to popup window coordinates. (After the window is displayed
the current canvas reverts to the full screen.) All drawing functions will happen in the popup window.
You can draw the window directly from code or use the Picture method to display a pre-made window.
The
SetHotSpot and
DeleteHotSpot functions allow for user feedback. The Popup
window can receive clicks in any defined hotspots. The window closes and the function returns
either when a hotspot is clicked or the number of seconds sent in the Popup function have elapsed,
whichever comes first. The Popup function return is the hotspot number clicked, or 0 if no hotspot is
clicked before pre-set time has elapsed.
Up to 4 hotspots can be assigned. Each can be any rectangular area of the window.
If a button is drawn in code the hotspot can be set by using the same coordinates used by SetCanvas
to draw the button (see message1.vbs). If a picture is used for window display it's necessary to find
the coordinates of hotspots in the picture. Message2.vbs demonstrates that option. The background in
message2.vbs was made in Paint Shop Pro. The coordinates of the buttons were found by hovering
the mouse while PSP displayed the X,Y coordinates in the status bar. A Popup window was then made
the same size as the picture and the picture was drawn onto it.
Once the window has been set up graphically it can be shown with the
Popup function. This is
a modal window. The component cannot be unloaded while the window is displayed. The
MaxShowTime property provides a way to deal with that while also providing a non-interactive
Popup function.
MaxShowTime is 120 seconds by default. It can be set to any number.
Using ob.Popup(0) will display the popup for MaxShowTime (seconds). Using any other number will
display the popup window for that number of seconds.
The window will display until a hotspot is clicked or
MaxShowTime has elapsed, whichever
comes first. To show a message box use a higher
MaxShowTime. If the window is never responded to
it will still close when
MaxShowTime has elapsed and allow the script to continue.
To show a non-interactive Popup send the number of display seconds required as the parameter to
the Popup function.
Back to Top
Method MakePopup(Left, Top, Width, Height)
• Switches drawing to popup window, sets popup size and placement.
ex.: ob.MakePopup 200, 200, 300, 200
Left, Top define the top left corner position of the popup window on the Desktop.
Width, Height define the size of the window.
MakePopup switches all drawing functions (including SetCanvas) from the screen to the popup window.
It also sizes and positions the popup window. MakePopup does not show the popup window.
To switch back to screen drawing use CancelPopup. Showing the window with the Popup
function also switches subsequent drawing functions back to the screen. In both cases, the new current canvas will
be the entire Desktop.
Back to Top
Method CancelPopup()
• Cancels MakePopup function.
ex.: ob.CancelPopup
CancelPopup will switch drawing functions back to the screen and delete
any drawing done since MakePopup was called.
Back to Top
Method SetHotSpot(Left, Top, Width, Height, HotNumber)
• Defines a hotspot in the popup window that can receive clicks.
ex.: ob.SetHotSpot 100, 100, 50, 30, 1
Left, Top, Width, Height define rectangular coordinates of the hotspot.
HotNumber can be 1, 2, 3 or 4. When the hotspot is clicked it's number
will be returned by the Popup function.
When a hotspot is set it is active for the life of the object. To deactivate
a hotspot use DeleteHotSpot. Hotspot numbers do not change when one is deleted.
Back to Top
Method DeleteHotSpot(HotNumber)
• Deactivates a defined hotspot.
ex.: ob.DeleteHotSpot 3
HotNumber is the hotspot to be deleted. It can be 1, 2, 3 or 4.
Hotspots do not need to be deleted before being redefined but any hotspot not
deleted will remain active. For example, if 3 buttons are shown in a popup window,
then another window is shown with 2 buttons, if hotspot 3 is not deleted it will
still be able to receive clicks.
Back to Top
Function Popup(Seconds)
• Shows the Popup window and returns result of input.
ex.: v = ob.Popup(0)
Seconds is number of seconds to display popup window.
Use 0 to display for MaxShowTime (default 120 seconds).
Popup will return when a hotspot is clicked or Seconds has elapsed,
whichever comes first. If no hotspot is clicked return will be 0. Otherwise,
return will be hotspot number.
Back to Top
Property MaxShowTime
• Sets maximum display time for Popup window.
ex.: ob.MaxShowTime = 10
The default MaxShowTime is 120. This is the maximum number of
seconds that the Popup window will show with the Popup function
before returning. For a non-interactive popup message, MaxShowTime
can be overridden by sending a lower number in the Popup function.
MaxShowTime prevents the possibility of the script hanging because of no input.
It also prevents leaving WScript running if the popup window gets buried or ignored.
Back to Top
Notes
Notes about functions:
• All coordinates and dimensions are in pixels.
• All colors are in 6-character RGB hex format. When a parameter takes a color the 6-char. hex code
is converted to system format for the drawing operation. If Color parameter is not 6 characters or is not
a valid hex code black will be used.
• All drawing coordinates are in relation to the "current canvas". The current canvas is the entire screen by default. The SetCanvas
method is used to re-define the current canvas as being any rectangular area of the screen or Popup window.
• JSDraw does not raise errors. For example, if the Picture method is used and the file path
is not valid, the picture will simply not be drawn. If SetCanvas is used with invalid parameters they
will be corrected as nearly as possible or the current canvas will be reset to the entire Desktop or
Popup window.
Back to Top
Copyright And License Information:
Applying to all of the components and sample VBScripts from JSWare:
You use them at your own risk.
None of the components or sample VBScripts includes code so unique and
brilliant as to justify laying claim to it. Therefore, feel free to use them as you wish,
providing you do not, yourself, lay claim to any JSWare scripts, components,
or parts thereof!
Specifically, the scripts and components may be used for commercial purposes
and may be packaged with software. No attribution is required. If components or whole
scripts are distributed please include a link to www.jsware.net so that recipients can check
for updates.
None of the code here may be redistributed under another license. That is, if a work
using code or components from JSWare is distributed with restrictions of any kind, the code
or components from
JSWare must be kept exempt from those restrictions. This includes, but is not limited
to, code sold for profit, code with usage limitations and code distributed as so-called
"Open Source" with redistribution requirements.
Joe Priestley