Functions(7x)

📦
version 2.2.12 · 4 versions
, in ubuntu resolute, ubuntu stonking

✨ NAME ✨

Functions — all the built-in AfterStep functions, bestie 💅

This is the Functions(7x) page from the AfterStep X11 window manager manual. Now let's get into it 🎀

🦋 CONFIGURATION OPTIONS 🦋

okay so this is the whole menu of config options you can use, and we are going through every single one, no skimming, no skipping 🙅‍♀️

  • Background "name" filename — swap your Background image to the file you pick 💖

It copies the image file you gave as filename into the user's non-configurable directory. Fair warning though: depending on the Background configuration in your look file, this may not have any effect at all. 😭

  • BackgroundForeign "name" filename — change the Background image to the file you pick, but make it ✨fancy✨

Works the same as Background, except it also generates a minipixmap from the image automagically. It also tries to determine whether the background should be fullscreen, and crops/scales it to the proper size. 🦋

  • Beep — makes the window manager issue a beep 🙈

Pretty useful eh? :)

  • BookmarkWindow "name" new_bookmark — drops a bookmark on the selected window 💌

Then you can use it later on to get back to that window.

  • Category "category-name" — generates a whole menu from every member belonging to the desktop category you name 👑

Example: Category "Modules" generates a menu of all AfterStep modules in afterstep/applications/modules.desktop.

  • CategoryTree — FIXME: add proper description here. 🫠

(yes literally, that's what the page says, i'm not making it up, they left us a TODO and i'm passing it straight to you 🙈)

  • ChangeColorscheme "name" filename — change the Color Scheme to the file you name 🎨

Copies the color scheme configuration file specified by filename into the user's non-configurable directory.

  • ChangeFeel "name" filename — change the Feel to the file you name ✨

Copies the feel configuration file specified by filename into the user's non-configurable directory.

  • ChangeLook "name" filename — change the Look to the file you name 💅

Copies the Look configuration file specified by filename into the user's non-configurable directory, to be used by AfterStep.

  • ChangeTheme "name" file_name — sets the current theme config file 👑

Such a config file may include settings for look, feel, menu, autoexec and any module.

  • ChangeThemeFile — installs a theme from a provided .tar, .tar.gz, or .tar.bz2 AfterStep theme file 📦
  • ChangeWindowDown [ "name" window_name ] — sends the pointer down the window list, backwards 🦋

Causes the pointer to move to the previous window in the list of windows for which CirculateSkip has not been specified.

The mouse will jump (going backwards) to the first window whose name (or icon name or class) matches window_name. The "name" entry then becomes required, but serves no purpose if the function is not called from a menu or popup.

  • ChangeWindowUp [ "name" window_name ] — sends the pointer through the window list too ⬆️

Causes the pointer to move to the previous window in the list of windows for which CirculateSkip has not been specified.

The mouse will jump to the first window whose name (or icon name or class) matches window_name. The "name" entry then becomes required, but serves no purpose if the function is not called from a menu or popup.

  • Close [ "name" ] — the polite goodbye 👋

First sends the WM_DELETE message, and if this is not understood, then the XKillClient(3) is sent to the window.

  • CursorMove horizontal vertical — moves the mouse pointer around by views 🖱️

Moves the mouse pointer by horizontal views in the x-direction, and vertical views in the y-direction. Either or both entries may be negative. Both horizontal and vertical values are expressed in percent of pages, so 100 would be one full view.

The CursorMove function should not be called from pop-up menus. no cap 🙅‍♀️
  • Delete [ "name" ] — asks a window very nicely to leave 🙏

Sends a WM_DELETE message to a window asking that it remove itself, frequently causing the application to exit.

  • Desk arg1 [ arg2 ] — teleports you to another desk 🌈

Changes current desk to another desk as surmised from the arguments supplied. If only arg1 is specified and is non-zero, then the current desk will become "desk + arg1" and arg2 is ignored. If arg1 is zero, then arg2 must be specified or no desk change will occur; and arg2 will specify the desk to switch to. Desk numbers are determined dynamically and must be between 2147483647 and -2147483648; meaning they can also be negative. 💀

  • DesktopEntry — FIXME: add proper description here. 🫠

(again!! another TODO!! we stay unserious 🙈)

  • Destroy [ "name" ] — the nuclear option 😤

Sends the XKillClient(3) to a window. Guaranteed to get rid of the window. no takebacks, periodt.

  • EndFunction — terminates a Complex Function definition 🔚
  • EndPopup — terminates a Popup definition 🔚
  • Exec "name" command [-options] — launches a sub process 🚀

Specifies a sub process to initiate. The "name" is required for ease of parsing. The command is the command or application to be invoked along with any desired -options.

  • ExecBrowser "name" URL — opens URL in your web browser 🌐
  • ExecEditor "name" filename — opens filename in your text editor 📝
  • ExecInTerm "name" command [-options] — launches a sub process, but for the terminal girlies 💻

Specifies a sub process to initiate. It is similar to Exec, though targeted at programs that need a terminal to run. The following terminal emulators are tried in order: aterm, rxvt, eterm, xterm.

  • Focus — makes your selected window the main character 👑

Moves the view or window as needed to make the selected window visible. Sets the keyboard focus to the selected window. Raises the window if needed to make it visible. Warps the pointer into the selected window in focus-follows-mouse mode. Does not de-iconify. This function is primarily handy when used with a module such as the WinList.

  • Folder "folder-name" — defines a slide-out folder inside the current folder 📂

The following button definitions will be placed inside of the subfolder, until a *Wharf ~Folder line is encountered. See the EXAMPLES section below for an example. Folders may be nested.

This is a Wharf specific Function.

  • Fullscreen — toggles the window's Fullscreen state 🖥️

Will disregard any AvoidCover windows and will try to make the window as big as the screen unless its hints set certain limitation on size. A window in Fullscreen mode cannot be Maximized. 😭

  • Function "function_name" — the big one, buckle up 🌀

There are also two situations where this might occur as well: as a function definition stanza, or in calling a previously defined function declaration.

Function  "function_name"  built-in_file  "action"  [ argument ] EndFunction

Specifies the definition of a complex function "function_name", which can later be bound to a mouse button or key using "function_name" to recall this declaration. built-in_command specifies which command will be performed, taking its syntax from this list of Built-In Commands/Functions. "action" specifies the action to take followed by any additional arguments needed by the built-in_command. Menus can be specified by using the Popup command, as long as the menu was defined earlier in the configuration file.

The trigger actions which are recognized are Immediate (can be shortened to "I"), Motion, Click, DoubleClick and TripleClick. Immediate actions are executed as soon as the function is activated, even if a window has not been selected. If there are actions other than immediate ones, afterstep will wait to see if the user is clicking, double-clicking, triple-clicking or dragging the mouse; then will execute only the built-ins from the function definition whose trigger action matches the action performed by the user. The clicking, double-clicking and triple-clicking concepts do not carry through to using keyboard shortcuts.

Two special functions exist: InitFunction and RestartFunction. The InitFunction will be called when afterstep is started for the first time in any X session, and can be used to start modules and begin programs. The RestartFunction will be called when afterstep is restarted. It can be used to re-start modules but probably should not be used to start programs. These two functions are defined in the autoexec file.

When calling a previously defined Function or a Function from a key-stroke combination, Function is simply used as a built-in command using the previously defined "action" from the same function_name.

Function  built-in_command  "action"  function_name

Refer to the feel.name files and below in EXAMPLES for examples.

  • GetHelp — pulls up the docs for you 📖

Runs the afterstepdoc script, that attempts to guess which web browser is available on the system, and then launches it to display HTML documentation for AfterStep.

  • GoToBookmark ["name" window_bookmark ] — zooms to a bookmarked window 🔖

Focuses the window specified by a previously placed window_bookmark.

  • GotoDeskViewport Desk+Vx+Vy — changes both current desk and viewport, two birds one stone 🐦
  • GotoPage x y — moves the desktop view to that page 🗺️

Moves the desktop view to page x y. The upper left page is (0,0), the upper right is (N,0), where N is one less than the current number of horizontal pages specified in the DeskTopSize command detailed in the Pager(1) man page. The lower left page is (0,M), and the lower right page is (N,M), where M is the desktop's vertical size as specified in the DeskTopSize command.

The GotoPage function should not be used in a pop-up menu. 🙅‍♀️
  • Iconify [ "name" ] [ value ] — minimize / un-minimize, your choice 🎀

Iconifies a window if it is not already iconified, or de-iconifies it if it is already iconified. If the optional argument value is positive, then only iconification will be allowed, and de-iconification will be inhibited. If the optional argument is negative, only de-iconification will be allowed.

  • InstallBackground "name" filename — copies the file to ~/.afterstep/backgrounds/ directory, so that it will show up in the menu, to be used for Root background 🖼️
  • InstallColorscheme "name" filename — copies the file to ~/.afterstep/colorschemes/ directory, so that it will show up in the menu, to be used as color scheme 🎨
  • InstallFeel "name" filename — copies the file to ~/.afterstep/feels/ directory, so that it will show up in the menu ✨
  • InstallFont "name" filename — copies the specified TTF file to ~/.afterstep/desktop/fonts/ directory, so that it could be used in look configuration 🔤
  • InstallIcon "name" filename — copies the specified image file to ~/.afterstep/desktop/icons/ directory, so that it could be used in look and database configuration 🌸
  • InstallLook "name" filename — copies the specified look file to ~/.afterstep/looks/ directory, so that it could be selected from the menu 💅

and bestie, that's literally not even all of it — more functions are coming, keep going 💖

🖼️ InstallThemeFile "name" filename

Okay so this one takes the theme file you point at and copies it into your ~/.afterstep/themes/ directory — so like, it becomes selectable from the menu afterward. Obsessed with the convenience. ✨

🎀 InstallTile "name" filename

Same vibe but for tiles, bestie: copies the image file you specify into ~/.afterstep/desktop/tiles/, so it's all set to be used in your look and database config. 🌸

💬 KIPCsendMessageAll

Sends a signal out to every single KDE application, refreshing their visual properties. Group announcement energy, fr fr 📣

💀 KillAllModulesByName

Kills all the AfterStep modules that match the name you give it. All of them. Periodt.

🔪 KillModuleByName "name" modulename

Kills the one specific module matching the name you provided. Surgical. 💅

✨ LargeMiniPixmap pixmap

Gives you a way to specify a pixmap to show off to the left of the menu item that invokes this menu, or up in the title of this menu. It's the one you use instead of MiniPixmap when you do not want a pixmap image scaled down — these stay full-size. The opposite of this is SmallMiniPixmap. 👑

See Also: MiniPixmap, SmallMiniPixmap, MenuMiniPixmaps.

📉 Lower [ "name" ]

Lets the user lower a window. Down you go, bestie. 🙈

🔄 MaxSwallow " window-name " command

Like Swallow, except the button gets resized to fit the application. Iconic little twist.

This is a Wharf specific Function.

🧚 MaxSwallowModule " window-name " command

Like MaxSwallow, except the command is an AfterStep module.

This is a Wharf specific Function.

🔲 Maximize [ "name" ] [ horizontal vertical ]

Makes the window flip back and forth between full-screen size and its normal size. And if you pass the optional horizontal and vertical args, you get control over the percentage of the full screen that the new window size becomes. Specifically: if horizontal > 0, then the horizontal dimension of the window gets set to horizontal*screen_width/100. Vertical resizing works the same way.

Bestie, values larger than 100 can be used, but with caution. ⚠️

The defaults for horizontal and vertical are 100s (i.e., fullscreen).

🖼️ MiniPixmap pixmap

Specifies a pixmap to display to the left of the menu item that invokes this menu, or in the title of this menu. The default pixmap size is 24x24 pixels, and you can adjust that size in Look via MiniPixmapSize. 🎀

See Also: MinipixmapSize, LargeMiniPixmap, SmallMiniPixmap, MenuMiniPixmaps.

🧩 Module ModuleName [ arguments ]

Tells AfterStep that ModuleName should be spawned.

Currently, lots of modules ship with afterstep. Wharf(1x) and Pager(1x) are two of the most popular ones. Wharf will normally be spawned during initialization instead of in response to a mouse binding or menu action. Modules can be short-lived transient programs, or — like Wharf — they can be intended to stick around for the whole duration of the X session. Modules will be terminated by afterstep before restarts and quits, if possible. 🫶

🚚 Move [ "name" ]

Lets the user move a window or an iconified app. Scoot scoot. 🛻

➖ Nop ""

Drops a horizontal line (an <HR> type html line) into a menu entry list. Divider, but make it menu. ✨

🌫️ Nop "name"

Drops a name into the menu, stippled — i.e., disabled and grayed-out. Not me putting a locked item in my menu 💀

📋 PasteSelection

This function is a stand-in for X clipboard copy-pasting, for when the application is missing it. So thoughtful of it. 🥰

📌 PinMenu ["name"]

Pins that menu on the desktop. Sticky. Iconic. ✨

So there are two situations where this can show up: either as a popup menu stanza definition, or when calling a previously defined menu declaration.

Popup  "popup_name"     built-in_command   "name"  [ argument ]
EndPopup

This specifies the definition of a complex menu popup "popup_name", which you can then bind to a mouse button or key by using "popup_name" to recall this declaration. built-in_command says which command gets performed, using its syntax from this list of Built-In Commands/Functions. "name" is the name that appears within the menu for that item — plus any arguments the built-in_command needs. The Popup definition wraps up with the keyword EndPopup. You can make sub-menus by calling the Popup built-in inside another Popup declaration, as long as that sub-menu was defined earlier in the config file. 🌀

Shortcut keys can be specified in the menu definition by putting an ampersand before a character. The ampersand is not displayed, but the character right after it is — over on the right side of the same entry. And if the user presses the corresponding key, that item gets activated as if it had been clicked. Only alphanumeric characters can be used as shortcut keys. The shift state of the keyboard is ignored when testing shortcut characters.

Heads up bestie: shortcut keys are not operative unless MENU_HOTKEYS was defined when building AfterStep. If WINDOWLIST_HOTKETS was also defined, then hot keys are automatically added to the WindowList when it's displayed.

When you're calling a previously defined menu, or a menu from a key-stroke combination, Popup is just used as a built-in command, with the "name" referring to the previously defined Popup definition's name.

Popups can be bound to keys through the use of the key modifier. You can operate popups without touching the mouse by binding them to keys and cruising with the up arrow, down arrow, and enter keys. Peep the feel.name files and the EXAMPLES section below for examples. ⌨️💅

⬇️ PutOnBack

Moves the target window to the bottom of its layer — or down one layer, if it's already at the bottom. No escape. 🙈

⬆️ PutOnTop

Moves the target window to the top of its layer — or up one layer, if it's already at the top. Main character energy, obviously. 👑

🔁 QuickRestart look|feel|look+feel

Makes AfterStep reload the specified config. Quick lil glow-up, no full restart needed. ✨

🚪 Quit [ "name" ]

Exits afterstep — which generally means X exits too. Closing time, bestie. 💀

🆙 Raise [ "name" ]

Lets the user raise a window. Up you go. 🫶

🔀 RaiseLower [ "name" ]

Alternates between raising and lowering a window — i.e. if it's raised, the window lowers, and vice versa. Flip-flop behavior, we love to see it. 🦋

🌀 Refresh [ "name" ]

Makes every window on the screen re-draw itself. Blink and glow up. ✨

📐 Resize [ "name" ]

Lets the user resize a window. Grab that corner. 💅

♻️ Restart "name" WindowManagerName

Restarts X(1) with the given WindowManagerName. If WindowManagerName is afterstep, then this forces afterstep to reread all its config files and reinitiate the whole session. If WindowManagerName is not in the default search path, then you should give the full path name. 🌈

🔄 RestartModuleByName

Restarts AfterStep modules that match the name you provide. Targeted reboot. 💫

🔁 RestartModuleList

Restarts every single AfterStep module. Yeah, all of them. 🔥

🚫 SET_FLAGS

Do not use. Reserved for use by AfterStep modules to set communication flags — identifying which messages a module wishes to receive. 🙅‍♀️

🚫 SET_MASK

Do not use. Reserved for use by AfterStep modules. Full stop. 🙅‍♀️

🚫 SET_NAME

Do not use. Reserved for use by AfterStep modules to identify themselves to AfterStep. 🙅‍♀️

💾 SaveWorkspace "name" file_name

Writes the list of currently running applications — with their position and desktop number — into the specified file. You can run this file later as a shell script to restore the state of your desktop. So cozy. 🥰

But ngl, this does not work for a lot of applications that don't provide the needed ICCCM properties on their windows. 😭

↔️ Scroll horizontal vertical

Scrolls the desktop's view by horizontal pages in the x-direction and vertical pages in the y-direction. Either entry — or both — can be negative. Both the horizontal and vertical values are expressed in percent of pages, so 100 would be one full page. Normally, scrolling stops at the edge of the desktop. But if the horizontal and vertical values are multiplied by 1000, then scrolling will wrap around at the edge of the desktop. 🌐

The scroll function should not be called from pop-up menus. ⚠️

📨 Send_WindowList

This Function is used by modules to get the list of open windows. Very behind-the-scenes of it. 🫶

❓ Set

FIXME: add proper description here.

Not the docs literally just saying FIXME 💀 iconic behavior honestly.

🗂️ SetLayer layer

Moves the target window to layer layer. Stack it right. 🎀

🪟 Shade [ "name" ]

Emulates the MacOS WindowShade feature. Once activated, the window becomes a titlebar and nothing else. Rolled-up realness. 🌸

🎨 SignalReloadGTKRCFile

Forces every GTK app to reload their gtkrc files. Refresh, bestie, refresh. ✨

📏 Size width height

Sets the size of the associated button, overriding every other size consideration. Because sometimes you just know what you want. 💅

The Wharf button size depends on several things, and the order of precedence is:

  1. Size definition
  2. MaxSwallow'd window size
  3. WharfPixmap size
  4. Use 64x64.

This is a Wharf specific Function.

🐣 SmallMiniPixmap pixmap

Specifies a pixmap to display to the left of the menu item that invokes this menu, or in the title of this menu. It's the one you use instead of MiniPixmap when you want the pixmap image scaled down to the smallest size. It gets sized based on the Menu font size plus eight pixels; the width is calculated to keep proportionality. Little and cute. 🦋

See Also: MiniPixmap, LargeMiniPixmap, MenuMiniPixmaps.

📌 Stick [ "name" ]

Makes a window sticky — it stays on screen when desks/views are switched — if it isn't already sticky, or non-sticky if it is already sticky. Toggle the clinginess. 🫶

🛑 StopModuleList

Stops every AfterStep module. Nap time for the whole squad. 😴

🐦 Swallow " window-name " command

Causes Wharf to run command, capture the first window whose name or resource is window-name, and display it in the associated button. The application window will be shrunk to fit the size of the button. Nom nom. 😋

This is a Wharf specific Function.

🌱 SwallowModule " window-name " command

Like Swallow, except the command is an AfterStep module.

This is a Wharf specific Function.

🪄 SwallowWindow "pattern" shell_command

This one will cause an already-opened window to be swallowed — whereas plain Swallow will run the application, if there are no windows matching pattern. Sneaky but useful. ✨

📸 TakeFrameShot "name" filename

Grabs a screenshot of the client window including frame decorations, and saves it in the specified files. Frame included, obviously, it's in the name. 💅

🖥️ TakeScreenShot "name" filename

Grabs a screenshot of the entire screen and saves it in the specified files. Whole desktop, one shot. 🔥

🪟 TakeWindowShot "name" filename

Grabs a screenshot of the client window — frame decorations not included, we're cropping those off — and saves it in the files you specify. 📸

  • Test — ⛔ do not use this one. It's an internal function, it's not for you, no cap.
  • Title "name" — drops in a title line of heading name into a popup or menu. cute little label moment 🏷️
  • ToggleLayer layer1 layer2 — says: hey, if this window is chillin' in layer1, actually put it in layer2. Otherwise? It goes into layer1. Either way you slice it, the window gets placed on top of the other windows in whichever target layer it lands in. 👑
  • TogglePage [ "name" ] — temporarily disables EdgeScroll. And the way you get edge scrolling back? You call this again. It's a toggle, bestie, it goes both ways 🔁
  • Transient — says this button is decorative, basically. It won't perform any action, it won't be pushable, and it won't have an associated balloon. It's just… there. 👻
  • UNLOCK — ⛔ same deal as Test: do not use, internal function, not your business, move along.
  • Wait app_name — this one is only meant to be used in afterstep functions, okay? What it does is pause the execution of a function until a new window named app_name shows up. And here's the slay part: afterstep stays fully functional the whole time it's waiting. It's especially useful inside InitFunction and RestartFunction when you're trying to start windows on specific desktops. ⏳✨
  • WarpBack [ "name" window_name ] — does the exact same thing as ChangeWindowDown, except it also uniconifies any iconified windows as it focuses on them. 😴➡️👀
  • WarpFore [ "name" window_name ] — same energy as ChangeWindowUp, but again: it uniconifies any iconified windows as it focuses on them. 😴➡️👀
  • WindowList [ arg1 arg2 ] — brings up the internal popup menu where the titles of every open application get listed. Picking an item from that list switches the current desk over to the application's desk, and raises the app if it's hanging out behind other windows. And if the app is iconified at that moment? It gets de-iconified, normal style. 🪟

So, generally speaking: if arg1 is an even number, the windows get listed using the window name — that's the name that shows up in the title-bar. If arg1 is an odd number, then the window's icon name is what's used instead.

And specifically, here's the breakdown:

  • if arg1 is 0, 1 or 2 → all windows on all desks get shown
  • if arg1 is 2 or 3 → only the windows on the current desk get shown
  • if arg1 is 4 or 5 → only the windows on the desk number you set with arg2 get shown
Heads up: any window that has WindowListSkip specified in its style will not show up in the window list. periodt. 🙅‍♀️
  • WindowsDesk new_desk [10000] — moves the selected window over to the desktop you named as new_desk. And if that second argument is set to 10000, then the first one gets treated as a relative desktop number instead. 🔢

<div align="center">🌸 that's a wrap on the function list, bestie 🌸</div>

This one ships out of the 3rd Berkeley Distribution, and it's documenting AfterStep v.2.2.12 — Functions(7x), the one and only. Now go forth and configure your heart out, you absolute main character 🫶💅✨

📦 where this page comes from