Reviewed and revised December 2023
? TAB(-10, AG_WALLPAPER); imagespec {,opcode {,dlgid}}; chr(127); Tab(-10,x) Syntax Notes
AG_WALLPAPER (39) provides a way to display a bitmap file as "wallpaper" for the background of the main A-Shell window.
Parameters
imagespec
File specification of an image. May be any image type recognized by AUI_CONTROL; JPG is probably the best option here. Either AMOS or native syntax may be used, but it will be interpreted relative to the PC. So if running on a Unix server with ATE, you must arrange for the file to be present on the PC before you can invoke it.
opcode
Code |
Description |
|---|---|
0 |
(default) Load new wallpaper, deleting any old wallpaper. If imagespec is null, then it just deletes any existing wallpaper. For dialogs, opcode must be 0. The only valid operation is to set the wallpaper to the dialog; it is destroyed when the dialog is deleted. |
1 |
Clear current wallpaper but save it. |
2 |
Restore previously saved wallpaper. |
+4 |
(Add 4). Normally, the wallpaper save and restore operations are destructive in the sense that "save" clears the current wallpaper, and an attempt to restore when there is no saved wallpaper will effectively delete the current wallpaper. To accommodate applications that want to be able to issue redundant save and restore operations, you can add 4 to opcode. Part of the incentive for this feature is that restoring a previously saved wallpaper is much faster than re-loading it from disk. |
+8 |
expand image to fit dialog |
+16 |
stretch (distort) as needed to fit |
dlgid
may either be the numeric or alphanumeric identifier for the dialog. If dlgid is zero or omitted, the command works on the main window as before. In most cases, you will want to create the dialog with the bgc parameter set to RGB_TRANSPARENT, else the background of static text controls will cover that portion of the wallpaper.
Response
none
Examples
Load examples:
? TAB(-10,AG_WALLPAPER);"bmp:pinup1.bmp";chr(127);
? TAB(-10,AG_WALLPAPER);"c:\my documents\wallpaper\rainforest.png";chr(127);
? TAB(-10,AG_WALLPAPER);"%MIAME%\bitmaps\clouds.jpg";chr(127);
? TAB(-10,AG_WALLPAPER);".\my life in pictures.jpg";chr(127);
? TAB(-10,AG_WALLPAPER);"";chr(127); ! (remove wallpaper)
Other examples:
? TAB(-10,AG_WALLPAPER);",1";chr(127); ! Save (and then clear) wallpaper
? TAB(-10,AG_WALLPAPER);",5";chr(127); ! Save (but don't clear) wallpaper
? TAB(-10,AG_WALLPAPER);",2";chr(127); ! Restore wallpaper; clear saved copy from memory
? TAB(-10,AG_WALLPAPER);",6";chr(127); ! Restore wallpaper only if there is saved wallpaper
Notes
Main window wallpaper is generally only useful when you are going to display a dialog on top of it. Otherwise, unless the wallpaper is very subtle, it makes it difficult to read text displayed on it. VUE and EZTYP temporarily disable the wallpaper (using opcodes 1 and 2). Only BMP files are supported.
For main window wallpaper, the load command (opcode 0) also automatically saves a copy if there is not already a saved copy. Thus you can do a load following by a restore (opcode 2) without first doing an explicit save.
When loading or clearing main window wallpaper, you need to then execute a screen clear command (e.g. ?TAB(-1,0)) in order to for the wallpaper to become fully visible or fully cleared.
AGCMD.LIT is handy for experimenting with main window wallpaper without the need for any programming. For example, the following commands load the wallpaper from a specified file and then remove it again. The XY=0 commands are necessary to finalize each wallpaper update operation.
.AGCMD WALLPAPER MYWP.PNG ; load wallpaper
.XY=0
.AGCMD WALLPAPER ; clear wallpaper (load null wallpaper)
.XY=0
History
2017 June, A-Shell 6.5.1606: Add opcode flags +8 and +16 to better display wallpaper. Previously, dialog wallpaper only supported opcode 0, in which case the image was tiled as needed to fit the dialog
2016 December, A-Shell 6.3.1540: AG_WALLPAPER now supports PNG and other image formats for main window wallpaper. This was always the case for dialog wallpaper, but until now the main window wallpaper was limited to BMP files.
2016 September, A-Shell 6.3.1527: Add dlgid and the ability to apply wallpaper to dialogs.
