~ubuntu-branches/ubuntu/lucid/sawfish/lucid-updates : revision 10

3

@settitle sawfish Programming Manual

4

@footnotestyle end

5

6

@set EDITION 0.6

7

@set VERSION 0.19

8

@set UPDATED 12 December 1999

9

@set UPDATE-MONTH December 1999

6

@set EDITION 0.11

7

@set VERSION 1.3

8

@set UPDATED 5 January 2004

9

@set UPDATE-MONTH January 2004

10

11

@ifinfo

12

@direntry

80

* Customization:: Supporting user-configuration

81

82

* Window Frames:: Decorating windows

83

@c * Viewports:: Subdivided desktop areas

83

84

* Workspaces:: Multiple desktop areas

85

* Multi-Head Environments:: Multiple monitors

86

* Window Placement:: Controlling placement of new windows

84

87

* Popup Menus:: Displaying menus

85

88

* Events:: Input event types

86

* Commands::

89

* Commands:: Functions you can invoke interactively

87

90

* Keymaps:: Bindings events to actions

88

91

* Event Loop:: Handling input events

89

92

* Miscellaneous Functions:: Useful features

168

171

Returns @code{t} when @var{arg} is a member of the color type.

169

172

@end defun

170

173

171

@defun get-color name

174

@defun get-color name &optional alpha

172

175

Returns the color object representing the color specified by the string

173

176

@var{name}. This is according to the standard X11 color specifiers,

174

177

either a named color from the @file{rgb.txt} database, or a string

176

179

or sixteen bits in hexadecimal, i.e. @samp{#RRGGBB} or

177

180

@samp{#RRRRGGGGBBBB}.

178

181

182

Optional argument @var{alpha} becomes the alpha value of

183

the returned color. It is passed through to @code{get-color-rgb}.

184

179

185

Signals an error if no known color has the name @var{name}.

180

186

@end defun

181

187

182

@defun get-color-rgb red green blue

188

@defun get-color-rgb red green blue &optional alpha

183

189

Return the color object representing the color with RGB components as

184

190

specified (each component ranging from 0 to 65535).

191

192

Optional argument @var{alpha} becomes the alpha value of the returned

193

color. Use an integer value in the range from 0 to 65535. Integers

194

outside that range are not supported, while non-integers such as

195

@code{nil} are silently converted to 65535 (fully opaque).

185

196

@end defun

186

197

187

198

Given a color object, it's possible to find both the actual rgb values

189

200

color.

190

201

191

202

@defun color-rgb color

192

Return a list of integers @code{(@var{red} @var{green} @var{blue})} the

193

actual color values of the color represented by object COLOR. The

194

individual values range from 0 to 65535.

203

Return a list of integers @code{(@var{red} @var{green} @var{blue}

204

@var{alpha})}, the actual color values of the color represented by

205

object COLOR. The individual values range from 0 to 65535.

206

@end defun

207

208

@defun color-rgb-8 color

209

Return a list of integers @code{(@var{red} @var{green} @var{blue}

210

@var{alpha})}, just like @code{color-rgb}. However, the color values

211

are scaled to fit a range from from 0 to 255.

195

212

@end defun

196

213

197

214

@defun color-name color

198

Return a string defining one of the X11 names used to specify the color

199

represented by the color object @var{color}. Note that this may well be

200

different to the name used when the color was originally allocated.

215

Return the name of the color represented by the color object

216

@var{color}. Note that this picks one name from the set of valid

217

names for this color; it may well be different to the name used when

218

the color was originally allocated.

219

220

The X11 name does not include alpha information.

201

221

@end defun

202

222

203

223

Where a color object is used to define the foreground color of a piece

220

240

Returns @code{t} if @var{arg} is a font object.

221

241

@end defun

222

242

243

Sawfish supports two types of fonts: X11 core fonts (fontsets and

244

fontstructs) and Xft fonts. Calling code must look up fonts by

245

giving both a name and a type: an @code{"xlfd"} argument indicates the

246

core fonts, and @code{"Xft"} indicates Xft fonts. These types are

247

always literal strings.

248

249

@defun font-type-exists-p type

250

Returns true if fonts with the type described by the string @var{type}

251

can be loaded, false otherwise.

252

@end defun

253

254

@defun get-font-typed type name

255

Return a font object representing the X11 font specified by the string

256

@var{name}. Argument @var{type} indicates the type of font to look

257

for; it must be one of the strings @code{"xlfd"} for a X11 core fonts

258

(based on fontsets or a fontstructs), or @code{"Xft"} for an Xft font.

259

260

Signals an error if @var{type} is not one of the literal strings

261

listed above. Also signals an error if no font named @var{name}

262

can be found within the requested type.

263

@end defun

264

223

265

@defun get-font name

224

Return a font object representing the X11 font specified by the string

266

Return a font object representing the X11 core font (fontset or

267

fontstruct) specified by the string @var{name}.

225

268

226

Signals an error if no font named @var{name} is available.

269

Signals an error if no font named @var{name} is available among the

270

X11 core fonts.

227

271

@end defun

228

272

229

273

Several functions allow the attributes associated with a font object to

234

278

string).

235

279

@end defun

236

280

281

@defun font-type font

282

Returns a string indicating the font's class. This is @code{"xlfd"}

283

for X11 core fonts, or @code{"Xft"} for Xft fonts.

284

@end defun

285

237

286

@defun font-height font

238

287

Returns the bounding height of glyphs in the font represented by object

239

288

@var{font}.

240

289

@end defun

241

290

291

@defun font-ascent &optional font

292

Returns the ascent of glyphs rendered using the font represented by

293

@var{font}. If no font argument is given, use the default font.

294

@end defun

295

296

@defun font-descent &optional font

297

Returns the descent of glyphs rendered using the font represented by

298

@var{font}. If no font argument is given, use the default font.

299

@end defun

300

242

301

@defun text-width string &optional font

243

302

Returns the number of horizontal pixels that would be required to

244

303

display the text @var{string} using font object @var{font} (or the

266

325

the font @var{font}, or @code{nil} if no such property exists.

267

326

@end defun

268

327

328

@defvar fonts-are-fontsets

329

True if the X fonts in use are fontsets. This will be false if

330

@code{setlocale} fails, or returns an ASCII locale, or if X doesn't

331

support the locale.

332

@end defvar

333

269

334

270

335

@node Images, Cursors, Fonts, Top

271

336

@chapter Images

279

344

Returns @code{t} when @var{arg} is a member of the image type.

280

345

@end defun

281

346

282

@defun make-image @var{file-name}

347

@defun make-image file-name &optional plist

283

348

Creates and returns an image object containing the image defined by the

284

349

contents of the file named @var{file-name} (a string). The

285

350

@code{image-load-path} directory provides the search path used while

288

353

All common image formats will likely be able to be loaded. But PNG,

289

354

JPEG and XPM should always be supported.

290

355

356

Argument @var{plist} becomes the property list of the returned image.

357

291

358

Signals an error if file called @var{file-name} may be found, or if an

292

359

image may not be constructed from the file.

293

360

@end defun

294

361

362

@defvar image-directory

363

Directory containing built-in Sawfish images. By default, this is

364

@code{@var{sawfish-directory}/images}.

365

@end defvar

366

295

367

@defvar image-load-path

296

368

A list of directory names. This defines the search path used when

297

loading images.

369

loading images. By default, this is @code{("."

370

@var{image-directory})}. Modifying @var{image-directory} does not

371

modify @var{image-load-path}.

298

372

@end defvar

299

373

300

374

@defun make-sized-image width height &optional color

303

377

image. If undefined, all pixels will be black.

304

378

@end defun

305

379

380

@defun make-image-from-x-drawable id &optional mask-id

381

Create and return an new image. The image is constructed by copying

382

an X Drawable (identified by @var{id}) into a Sawfish image object.

383

The function automatically handles depth conversion.

384

385

If @var{mask-id} is given, it identifies another X Drawable. Black

386

pixels in this drawable indicate transparent pixels in the image

387

object (non-black pixels have no effect on the image object).

388

@end defun

389

306

390

@defun copy-image image

307

391

Returns a newly allocated image object, an exact copy of the image

308

392

object @var{image}.

315

399

316

400

@defun flip-image-horizontally image

317

401

Flip the contents of @var{image} about the vertical axis.

402

This is a mutating operation that returns the modified argument.

318

403

@end defun

319

404

320

405

@defun flip-image-vertically image

321

406

Flip the contents of @var{image} about the horizontal axis.

407

This is a mutating operation that returns the modified argument.

322

408

@end defun

323

409

324

410

@defun flip-image-diagonally image

325

411

Flip the contents of @var{image} about an axis running from the

326

412

top-left corner to the bottom-right corner of the image.

413

This is a mutating operation that returns the modified argument.

327

414

@end defun

328

415

329

416

As with many of the other types, arbitrary state may be associated with

359

446

360

447

@defun set-image-border image left right top bottom

361

448

Sets the border of @var{image}.

449

450

The number associated with each edge of the image defines the number of

451

pixels adjacent to that edge that @emph{will not} be scaled.

362

452

@end defun

363

453

364

454

The shape of the image may also be specified, this defines which pixels

365

455

are treated as being transparent. Each image may define a single color

366

456

as marking transparent pixels.

367

457

458

Image shapes are not supported under GDK Pixbuf. Sawfish will

459

print a diagnostic message to @code{STDERR} if the function is called

460

without being supported.

461

368

462

@defun image-shape-color image

369

463

Return the color marking transparent pixels in @var{image}, or

370

464

@code{nil} if no such color has been specified.

386

480

applied to the associated attribute when rendering the image.

387

481

388

482

The four types are @code{red}, @code{green}, @code{blue} and @code{nil}

389

(all colors).

483

(all colors). The argument must be @code{eq} to one of those symbols.

390

484

@end defun

391

485

392

486

@defun set-image-modifier image type gamma brightness contrast

393

487

Set the image modifier of @var{image} defined by @var{type}.

488

@var{Type} may be one of the values of (not the symbols) @code{red},

489

@code{green} or @code{blue}.

394

490

@end defun

395

491

396

492

There are also several other functions manipulating images:

406

502

@end defun

407

503

408

504

@defvar default-bevel-percent

409

Default height of drawn bevels, as a percentage.

505

Default height of drawn bevels, as a percentage. Normally 50%.

410

506

@end defvar

411

507

412

508

@defun clear-image image &optional color

419

515

upper-left corner, working outwards.

420

516

@end defun

421

517

518

@defun scale-image image width height

519

Return a copy of @var{image}, scaled to @var{width} by @var{height}

520

pixels.

521

@end defun

522

523

@defun composite-images image1 image2 &optional x y

524

Copy the contents of @var{image2} into @var{image1}. @var{Image2} is

525

cropped to fit. Arguments @var{x} and @var{y} indicate the position

526

in @var{image1} of the top-left corner of @var{image2}. If not

527

supplied, they default to 0.

528

@end defun

529

530

@defun crop-image image x y width height

531

Return a new image that is a rectangular section of @var{image}. The

532

result image starts at pixel (@var{x}, @var{y}) in @var{image}, and

533

extends over @var{width} and @var{height} pixels in @var{image}.

534

535

When the cropped image extends beyond the boundary of @var{image}, the

536

behavior is undefined.

537

@end defun

538

539

The following functions allow users to manipulate images on a

540

pixel-by-pixel level. They all use a list representation for pixels:

541

(@var{r}, @var{g}, @var{b}, @var{a}) indicating the red, green, blue

542

and alpha components

543

544

@defun image-ref image x y

545

Return a list (@var{r}, @var{g}, @var{b}, @var{a}) of the red, green,

546

blue and alpha components of the pixel (@var{x}, @var{y}) in

547

@var{image}.

548

549

When the pixel position extends outside the bounds of the image, the

550

behavior is undefined.

551

@end defun

552

553

@defun image-set image x y pixel

554

Set the pixel at (@var{x}, @var{y}) in @var{image} to @var{pixel}.

555

@var{Pixel} is a list of four numbers (@var{r}, @var{g}, @var{b},

556

@var{a}), the red, green, blue and alpha components.

557

558

When the pixel position extends outside the bounds of the image, the

559

behavior is undefined.

560

@end defun

561

562

@defun image-map xform image

563

Transform each pixel in @var{image} in place by calling @var{xform} on

564

each pixel in the image.

565

566

@var{Xform} takes a single argument, a four element list (@var{r},

567

@var{g}, @var{b}, @var{a}) indicating the red, green, blue and alpha

568

components of a pixel. @var{Xform} should return the new value for

569

the pixel it was given. The return format is the same four-element

570

list.

571

572

@var{Xform} is allowed to return @code{nil}. In this case,

573

@code{image-map} immediately returns an invalid object.

574

@end defun

575

576

@defun image-fill generator image

577

Set each pixel in @var{image} based on the results of calling

578

@var{generator}.

579

580

@var{Generator} takes two arguments: the X and Y coordinates of a

581

pixel. It returns a four element list (@var{r}, @var{g}, @var{b},

582

@var{a}) indicating the red, green, blue and alpha components of a

583

pixel. This new pixel replaces the current pixel contents at (X, Y).

584

585

@var{Generator} is allowed to return @code{nil}. In this case,

586

@code{image-map} immediately returns an invalid object.

587

@end defun

588

589

@defun pixmap-cache-control max

590

Tell Sawfish to cache no more than @var{max} pixels. Returns a

591

four-element list indicating the current cache status:

592

@code{(@var{max-cached-pixels}, @var{cached-pixels}, @var{hits},

593

@var{misses})}.

594

@end defun

595

422

596

423

597

@node Cursors, Windows, Images, Top

424

598

@chapter Cursors

425

599

@cindex Cursors

426

600

427

Cursors define the shape and hot-spot of the mouse pointer's image. A

428

lisp type is provided for manipulating these objects.

601

Cursors define the shape and hot-spot of the mouse pointer's image. A

602

lisp type is provided for manipulating these objects. In addition,

603

Sawfish provides functions for manipulating the position of the

604

cursor.

605

606

@menu

607

* Cursor Appearance::

608

* Cursor Positioning::

609

@end menu

610

611

@node Cursor Appearance, Cursor Positioning, Cursors, Cursors

612

@section Cursor Appearance

429

613

430

614

@defun cursorp arg

431

615

Returns @code{t} if @var{arg} is a member of the cursor type.

439

623

Possible @var{data} values are an integer representing a glyph in the

440

624

standard X11 cursor font, or a four-element vector.

441

625

442

If a vector the format is @code{[@var{image} @var{mask} @var{fg}

626

The format for a vector is @code{[@var{image} @var{mask} @var{fg}

443

627

@var{bg}]} where @var{image} and @var{mask} are the filenames of

444

628

standard X11 bitmaps, and @var{fg} and @var{bg} are colors (or names of

445

629

colors). All bitmap files are searched for using the

451

635

@var{bg} (either color objects or the names of colors).

452

636

@end defun

453

637

454

@defun default-cursor cursor

638

@defun default-cursor &optional cursor

455

639

Set the cursor object displayed in the root window, and in parts of

456

640

window frames that have no other cursor specified, to @var{cursor}.

641

642

If called with no argument, simply return the current such cursor

643

object.

457

644

@end defun

458

645

459

646

So that the integer indices of glyphs in the X11 cursor font do not

488

675

The glyphs associated with these names are shown in Appendix I, of

489

676

Volume Two, @cite{Xlib Reference Manual}.

490

677

678

@node Cursor Positioning, , Cursor Appearance, Cursors

679

@section Cursor Positioning

680

681

Sawfish provides one basic command for adjusting the relative position

682

of the cursor.

683

684

@defun move-cursor right down

685

Move the cursor @var{right} pixels to the right across the screen, and

686

@var{down} pixels down the screen. The cursor stops at the edge of

687

the screen (although in multi-head environments, this may not be at

688

the edge of the display).

689

@end defun

690

691

There are also more specialized cursor movement commands.

692

693

@defun move-cursor-left-fine

694

@defunx move-cursor-right-fine

695

@defunx move-cursor-up-fine

696

@defunx move-cursor-down-fine

697

Move the cursor 1 pixel in the indicated direction.

698

@end defun

699

700

@defun move-cursor-left

701

@defunx move-cursor-right

702

@defunx move-cursor-up

703

@defunx move-cursor-down

704

Move the cursor @code{move-cursor-increment} pixels in the indicated

705

direction.

706

@end defun

707

708

@defvar move-cursor-increment 16

709

The @code{move-cursor-@var{DIRECTION}} functions move this cursor this

710

many pixels at a time.

711

@end defvar

491

712

492

713

@node Windows, Customization, Cursors, Top

493

714

@chapter Windows

515

736

Return a window object with name @var{name}, or @code{nil}.

516

737

@end defun

517

738

739

@defun get-window-by-name-re name

740

Return a window object with name matching regular expression

741

@var{name}, or @code{nil}.

742

@end defun

743

744

@defun activate-window window

745

Do everything necessary to make @var{window} active, including raising

746

it, giving it focus, etc. Certain steps may be skipped (e.g., giving

747

focus) if the window doesn't allow that operation.

748

@end defun

749

750

@defun filter-windows pred

751

Return the list of windows (mapped or unmapped) that match the

752

predicate function @var{pred}.

753

@end defun

754

755

@defun map-windows function

756

Call @code{(@var{function} @var{window})} on all existing windows.

757

Returns the value of the last @var{function} invocation. If any

758

@var{function} returns @code{nil}, @code{map-windows} returns

759

@code{nil} immediately.

760

@end defun

761

762

@defun window-class window

763

Return the class that @var{window} belongs to as a string, or nil if

764

@var{window} has no associated class.

765

@end defun

766

767

@defun get-window-wm-protocols window

768

Return a list of symbols defining the X11 window manager protocols

769

supported by client @var{window}.

770

@end defun

771

772

@defun window-supports-wm-protocol-p window atom

773

Return true if @var{window} includes @var{atom} in its

774

@code{WM_PROTOCOLS} property.

775

@end defun

776

518

777

@menu

519

778

* Window Property Lists::

779

* Window Types::

520

780

* Window Attributes::

521

781

* Input Focus::

522

782

* X Properties::

526

786

* Destroying Windows::

527

787

* Shading Windows::

528

788

* Iconifying Windows::

789

* Window Stickiness::

790

* Ignored Windows::

529

791

* Maximizing Windows::

792

* Animating Windows::

793

* Cycling Between Windows::

794

* Window Groups::

530

795

@end menu

531

796

532

797

533

@node Window Property Lists, Window Attributes, , Windows

798

@node Window Property Lists, Window Types, , Windows

534

799

@section Window Property Lists

535

800

@cindex Window property lists

536

801

@cindex Property lists, of windows

550

815

stores with each window, since these properties are internal to the

551

816

window manager (@pxref{X Properties}).

552

817

818

For a list of the standard window properties, see @ref{Standard Properties}.

819

553

820

@defun window-put window property value

554

821

Set the lisp property named @var{property} (a symbol) associated with

555

window object @var{window} to @var{value}.

822

window object @var{window} to @var{value}. Note that these are Lisp

823

properties not X properties.

556

824

@end defun

557

825

558

826

@defun window-get window property

559

Return the window property named @var{property} associated with the

560

window object @var{window}, or @code{nil} if no such property exists.

561

@end defun

562

563

For a list of the standard window properties, see @ref{Standard

564

Properties}.

565

566

567

@node Window Attributes, Input Focus, Window Property Lists, Windows

827

Return the window property named @var{property} (a symbol) associated

828

with the window object @var{window}, or @code{nil} if no such property

829

exists. Note that these are Lisp properties not X properties.

830

@end defun

831

832

@defun map-window-properties function window

833

Call @code{(@var{function} @var{property} @var{value})} on each of the

834

Lisp properties bound to @var{window}. Returns the value of the last

835

@var{function} invocation. If any @var{function} returns @code{nil},

836

@code{map-window-properties} returns @code{nil} immediately.

837

@end defun

838

839

840

@node Window Types, Window Attributes, Window Property Lists, Windows

841

@section Window Types

842

@cindex Window types

843

@cindex Types, of windows

844

@cindex Windows, types of

845

846

Transient windows are pop-up or dialog windows associated with a main

847

application. They tend to have less window decorations, and are

848

intended to last a short time only.

849

850

@defun window-transient-p arg

851

Returns @code{t} if @var{arg} represents a transient window.

852

@end defun

853

854

@defun mark-window-as-transient w

855

Mark that the window associated with object @var{w} is a transient

856

window.

857

@end defun

858

859

@defun transient-of-p child parent

860

Return true if window @var{child} is directly a transient for window

861

@var{parent}, false otherwise.

862

@end defun

863

864

@defun indirect-transient-of-p descendant ancestor

865

Return true if window @var{descendant} is (directly or indirectly) a

866

transient for window @var{ancestor}, false otherwise.

867

@end defun

868

869

@defun transient-parents child &optional indirectly

870

Return the list of windows that window @var{child} is a transient

871

for. If @var{indirectly} is true, then return the list of all

872

ancestors rather than parents.

873

@end defun

874

875

@defun transient-children parent &optional indirectly

876

Return the list of windows that are transients for window

877

@var{parent}. If @var{indirectly} is true, then return the list of

878

all descendants rather than children.

879

@end defun

880

881

@defun transient-group window &optional by-depth

882

Return the list of windows which is either a transient window for

883

window @var{window}, or a window which @var{window} is a transient

884

for. This always includes W. The `transient window for' relation holds

885

for windows which are direct or indirect transients of the parent

886

window in question.

887

888

If the @var{by-depth} argument is true, then the retrurned list is in

889

stacking order.

890

@end defun

891

892

@defun map-transient-group fun window

893

Map the single argument function @var{fun} over all windows in the same

894

transient group as window @var{window}.

895

@end defun

896

897

@defun raise-window-and-transients window

898

Raise window @var{window} to its highest allowed position in the

899

stacking order. Also raise any transient windows that it has.

900

@end defun

901

902

@defun lower-window-and-transients window

903

Lower window @var{window} to its lowest allowed position in the

904

stacking order. Also lower any transient windows that it has.

905

@end defun

906

907

@defun raise-lower-window-and-transients window

908

If window @var{window} is at its highest possible position, then lower

909

it to its lowest possible position. Otherwise raise it as far as

910

allowed. Also changes the level of any transient windows it has.

911

@end defun

912

913

@defvr Customizable focus-windows-when-mapped

914

Focus on application windows when they first appear. Defaults to

915

true, must be true or false.

916

@end defvr

917

918

@defvar decorate-transients

919

Decorate dialog windows similarly to application windows. Defaults to

920

false.

921

@end defvar

922

923

Desktop windows are root windows or viewport windows.

924

925

@defun desktop-window-p arg

926

Returns @code{t} if @var{arg} represents a desktop window.

927

@end defun

928

929

@defun mark-window-as-desktop w

930

Mark that the window associated with object @var{w} is a desktop

931

window.

932

@end defun

933

934

@defvar desktop-window-properties

935

List of properties set (to true) on windows marked as desktops.

936

Defaults to

937

@lisp

938

'(fixed-position sticky sticky-viewport)

939

@end lisp

940

@end defvar

941

942

@defvar desktop-window-depth

943

The stacking depth of desktop windows. Defaults to -4.

944

@end defvar

945

946

Dock windows are simply those with the @code{dock-type} property.

947

GNOME panels are one example. Sawfish does not currently assign them

948

any special behavior.

949

950

@defun dock-window-p arg

951

Returns @code{t} if @var{arg} represents a dock window.

952

@end defun

953

954

@defun mark-window-as-dock w

955

Mark that the window associated with object @var{w} is a dock

956

window.

957

@end defun

958

959

@defvar dock-window-properties

960

List of properties set (to true) on windows marked as docks.

961

Defaults to

962

@lisp

963

'(window-list-skip cycle-skip fixed-position focus-click-through

964

avoid no-history never-iconify never-maximize sticky

965

sticky-viewport placed)

966

@end lisp

967

@end defvar

968

969

@defvar dock-window-depth

970

The stacking depth of dock windows. Defaults to 0.

971

@end defvar

972

973

@node Window Attributes, Input Focus, Window Types, Windows

568

974

@section Window Attributes

569

975

@cindex Window attributes

570

976

@cindex Attributes, of windows

579

985

be the same as the normal name.

580

986

@end defun

581

987

988

Sawfish provides functions to ensure that window names are unique.

989

990

@defun uniquify-name proposal existing

991

Uniquify the string @var{proposal} against the list of strings

992

@var{existing}. Uses the format string @code{uniquify-name-format} to

993

generate unique names.

994

@end defun

995

996

@defvar uniquify-name-format

997

Format to create unique window names. Defaults to @code{"%s [%d]"}.

998

@end defvar

999

1000

@deffn Function uniquify-window-name window

1001

@deffnx Command uniquify-window-name window

1002

Force @var{window} to have a unique title.

1003

@end deffn

1004

582

1005

@defun window-icon-name window

583

1006

Return the icon name associated with @var{window}.

584

1007

@end defun

603

1026

return an integer defining its xid, otherwise return @code{nil}.

604

1027

@end defun

605

1028

1029

@defun root-window-id

1030

Returns the numeric ID of the root window of the managed screen.

1031

@end defun

1032

606

1033

@defun window-group-id window

607

Return an integer defining the xid of the leader of the group that

608

@var{window} is a member of, or @code{nil} if @var{window} is not a

609

member of a group.

1034

If @var{window} is part of a group, return the X window id of the

1035

leader of that group. Otherwise return @code{nil}.

610

1036

@end defun

611

1037

612

1038

@defun window-wants-input-p window

616

1042

property).

617

1043

@end defun

618

1044

1045

@defun window-really-wants-input-p window

1046

Return @code{nil} if the client window associated with object

1047

@var{window} should never be focused, @code{t} otherwise.

1048

@end defun

1049

619

1050

@defun window-dimensions window

620

1051

Returns a cons cell @code{(@var{width} . @var{height})} defining the

621

1052

dimensions of the client window associated with object @var{window}.

633

1064

@code{max-width}, @code{height-inc}, @code{width-inc},

634

1065

@code{min-aspect}, @code{max-aspect}, @code{base-height},

635

1066

@code{base-width}, @code{user-position}, @code{program-position},

636

@code{user-size}, @code{program-size}, @code{window-gravity}.

1067

@code{user-size}, @code{program-size}, @code{window-gravity},

1068

@code{border-size}.

637

1069

@end defun

638

1070

639

1071

@defun window-visibility window

642

1074

@code{partially-obscured} or @code{unobscured}.

643

1075

@end defun

644

1076

1077

@defun window-urgent-p window

1078

Return @code{t} if the ``Urgency'' hint of the window associated with

1079

@var{window} is set.

1080

@end defun

1081

645

1082

646

1083

@node Input Focus, X Properties, Window Attributes, Windows

647

1084

@section Input Focus

660

1097

661

1098

@defun set-input-focus window

662

1099

Sets the focus to the client window associated with @var{window}.

1100

1101

If @var{window} is @code{nil}, then no window will have the focus.

663

1102

@end defun

664

1103

1104

The window manager is responsible for switching the input focus from

1105

client window to client window. Sawfish implements several

1106

@dfn{focus modes} that provide this behavior. Each focus mode is

1107

bound to a symbol; the implementation is bound to that symbol's

1108

@code{focus-mode} property slot.

1109

665

1110

@defvar focus-mode

666

1111

Defines the current method of using the mouse to assign the input

667

focus. Possible values are @code{enter-exit}, @code{enter-only} and

668

@code{click}.

669

@end defvar

670

671

@defvar focus-proxy-click

672

When in click-to-focus mode, the focus-assigning click is only passed

673

through to the client window if this variable is non-@code{nil}.

1112

focus. This is a symbol from the list @code{focus-modes}.

1113

@end defvar

1114

1115

@defvar focus-modes

1116

A list containing all names of focus modes. The built-in values are

1117

@code{enter-exit}, @code{enter-only} and @code{click}.

1118

@end defvar

1119

1120

It is possible to add additional focus modes by defining your own

1121

handler function. The handler function must obey a

1122

``focus-mode-handler'' protocol.

1123

1124

@deftp {Function Protocol} focus-mode-handler window event-name &optional args

1125

A function that implements the @code{focus-mode-handler} protocol can

1126

be used to define a focus mode. A @code{focus-mode-handler} responds

1127

to events associated with windows.

1128

1129

Argument @var{window} is the window that received this event.

1130

1131

Argument @var{event-name} is one of the following symbols:

1132

1133

@table @code

1134

@item pointer-in

1135

@itemx pointer-out

1136

The pointer has entered or exited the window. The handler is

1137

responsible for checking whether an entered window wants input events.

1138

The desktop never receives @code{pointer-in} or @code{pointer-out};

1139

only normal windows do.

1140

1141

@item

1142

@item enter-root

1143

@itemx leave-root

1144

The pointer has entered or exited the desktop (which is the

1145

@var{window} argument). Normal windows never receive

1146

@code{enter-root} or @code{leave-root}.

1147

1148

@item focus-in

1149

@itemx focus-out

1150

The window argument has gotten or lost focus. Note that the

1151

@code{focus-in} handler is not responsible for updating the

1152

window-order list.

1153

1154

@item before-mode-change

1155

@itemx after-mode-change

1156

Sawfish sends these synthetic events to each window before/after

1157

changing that window's focus mode. When the global focus mode

1158

changes, all windows get these events.

1159

1160

@item add-window

1161

Sawfish sends this event to every window immediately after mapping it.

1162

Handlers can use this to initialize window-internal data structures.

1163

1164

@item warp-if-necessary

1165

Warp the cursor to the window if doing so would make the cursor

1166

position ``consistent'' with the focus mode. For example, in

1167

@code{enter-exit} mode we warp the cursor if it is not already in this

1168

window. In @code{enter-only} mode, we warp the cursor if it is in

1169

another window, but not if it is over the desktop---a window would not

1170

lose focus when the cursor moved from it to the desktop.

1171

@end table

1172

1173

The protocol allows for any number of additional arguments, but does

1174

not define any. Any handler function must be prepared to receive and

1175

ignore them.

1176

1177

Unsupported events may be ignored. The return value of this function

1178

is ignored.

1179

@end deftp

1180

1181

@defun define-focus-mode name fun

1182

Defines a new focus mode called @var{name} (a symbol). The focus-mode

1183

handler @var{fun} implements this focus mode.

1184

1185

See the documentation for @code{focus-mode-handler} for more

1186

information.

1187

@end defun

1188

1189

@defun set-focus-mode window mode

1190

Set the focus mode of window @var{window} to @var{mode}.

1191

This triggers @code{before-mode-change} and @code{after-mode-change}

1192

focus-mode events on @var{window}.

1193

@end defun

1194

1195

@defun warp-pointer-if-necessary window

1196

Generate a @code{warp-if-necessary} event and send it to the window's

1197

focus function.

1198

@end defun

1199

1200

@defvar focus-click-through

1201

When in @code{click} focus mode, the focus-assigning click is only

1202

passed through to the client window if this variable is @code{t} (the

1203

default).

674

1204

675

1205

This option may be set on a per-window basis by setting the

676

1206

@code{focus-click-through} property of the window (using the

677

1207

@code{window-put} function).

678

1208

@end defvar

679

1209

1210

@defvar focus-ignore-pointer-events

1211

When true, pointer in/out events don't cause focus changes. This is

1212

independent of the current focus mode.

1213

@end defvar

1214

1215

@defvar focus-within-click-event

1216

When true, the current command is being called from within a

1217

click-to-focus button press event.

1218

1219

This is a fluid object, not an ordinary variable.

1220

@end defvar

1221

680

1222

Sawfish also maintains the order in which windows were recently

681

1223

focused.

682

1224

699

1241

Remove window object @var{window} from the focus stack.

700

1242

@end defun

701

1243

1244

@defun window-order-most-recent &optional windows

1245

Return the most-recently focused window in the current workspace. If

1246

the optional argument @var{windows} is given, it must be a list of

1247

windows. In that case, the function will return the most-recently

1248

focused window from that list.

1249

@end defun

1250

702

1251

@defun window-order-focus-most-recent

703

Focus the most-recently-focused window on the current viewport of the

704

current workspace.

705

@end defun

706

1252

Focus the most-recently-focused window of the current workspace.

1253

@end defun

1254

1255

@defvar focus-dont-push

1256

When true, focusing a window doesn't change it's position in the stack of

1257

most-recently focused windows.

1258

@end defvar

1259

1260

@defun window-in-cycle-p window &keyword ignore-cycle-skip

1261

Returns @code{t} if the window @var{window} should be included when

1262

cycling between windows. Desktop windows and those with the

1263

@code{cycle-skip} property should normally not be included.

1264

1265

When @code{t}, the @var{ignore-cycle-skip} keyword argument

1266

forces the function to include windows with the @code{cycle-skip}

1267

property.

1268

@end defun

1269

1270

@defun focus-push-map window keymap

1271

@defunx focus-pop-map window

1272

Maintain a two-element keymap stack for @var{window}.

1273

1274

@code{focus-push-map} makes @var{keymap} current for @var{window}, but

1275

saves the existing keymap. We can restore this existing keymap with

1276

@code{focus-pop-map}.

1277

1278

These functions are intended to support click-to-focus. They enforce

1279

certain sanity rules: pushing into a two-element stack will only

1280

overwrite the top element, while popping a one-element stack has no

1281

effect.

1282

@end defun

1283

1284

@defun autoload-focus-mode name func

1285

MISSING. This does not seem to be used anywhere, and its behavior is

1286

unclear.

1287

@end defun

1288

1289

@defun select-window

1290

Waits for the user to left-click on a window, and returns that window.

1291

The mouse cursor changes shape, and all normal input events are

1292

suppressed until a window is selected.

1293

@end defun

1294

1295

@defvar select-window-cursor-shape

1296

The cursor shape to use when selecting a window. Defaults to

1297

@code{crosshair}.

1298

@end defvar

707

1299

708

1300

@node X Properties, Window Stacking, Input Focus, Windows

709

1301

@section X Properties

779

1371

780

1372

It's also possible to detect when the value of any property associated

781

1373

with a managed window changes, using the @code{property-notify-hook}.

782

@xref{Standard Hooks}.

1374

@xref{Standard Hooks}. The following convenience function takes

1375

advantage of this hook:

1376

1377

@defun call-after-property-changed prop fun

1378

Arrange for function @var{fun} to be called with arguments

1379

@samp{(window property state)} when the X11 property named @var{prop}

1380

(a symbol) changes. @var{Prop} may also be a list of property names

1381

to monitor.

1382

@end defun

783

1383

784

1384

785

1385

@node Window Stacking, Moving and Resizing Windows, X Properties, Windows

789

1389

@cindex Windows, stacking

790

1390

791

1391

The stacking order of the display defines the order in which windows

792

are shown, from topmost to bottommost.

1392

are shown, from topmost to bottommost. Sawfish maintains this list.

1393

Raising or lowering windows changes their positions in this list.

1394

1395

@menu

1396

* Stacking Order::

1397

* Raising and Lowering Windows::

1398

@end menu

1399

1400

@node Stacking Order, Raising and Lowering Windows, Window Stacking, Window Stacking

1401

@subsection Stacking Order

793

1402

794

1403

@defun stacking-order

795

1404

Return a list of window objects defining the current stacking order of

796

1405

all client windows, from top-most to bottom-most.

797

1406

@end defun

798

1407

1408

@defun mapped-stacking-order

1409

Similar to @code{stacking-order}, but only returns windows that are

1410

mapped.

1411

@end defun

1412

799

1413

@defun restack-windows list

800

1414

Restack all client windows specified in the list of window objects

801

1415

@var{list} in the order they occur in the list (from top to bottom).

802

1416

The stacking order of any unspecified windows isn't affected.

803

1417

@end defun

804

1418

805

@defun x-raise-window window

806

Raise the client window associated with object @var{window} to the top

807

of the display.

808

@end defun

809

810

1419

Sawfish allows the stacking order to be managed as a sequence of

811

1420

layers, with windows being assigned a particular depth within the

812

1421

order. For any given window with depth @var{d}, it will be above all

823

1432

@var{depth}.

824

1433

@end defun

825

1434

1435

@defun window-depth window

1436

Returns the depth of @var{window}.

1437

@end defun

1438

826

1439

@defun set-window-depth window depth

827

Set the stacking depth of @var{window} to @var{depth}, then restacks

1440

Sets the stacking depth of @var{window} to @var{depth}, then restacks

828

1441

the windows to reflect this change.

829

1442

@end defun

830

1443

848

1461

@code{progn}.

849

1462

@end defmac

850

1463

851

For the following functions, when called interactively they all operate

852

on the window that received the current event, or alternatively the

853

currently focused window.

854

855

@deffn Command lower-window window

1464

@defun restack-window w

1465

Assuming that the current stacking order is in a consistent state

1466

except, possibly, for the position of window @var{w}, restore the

1467

consistent state including window @var{w}. This is achieved by raising

1468

or lowering window W as appropriate.

1469

@end defun

1470

1471

@node Raising and Lowering Windows, , Stacking Order, Window Stacking

1472

@subsection Raising and Lowering Windows

1473

@cindex Windows, raising

1474

@cindex Windows, lowering

1475

1476

Over time, Sawfish has accumulated several subtle variations of

1477

functions for raising and lowering windows. One set of functions

1478

operates on single windows.

1479

1480

@deffn Function lower-window window

1481

@deffnx Command lower-single-window window

856

1482

Lower @var{window} to the bottom of its stacking depth.

857

1483

@end deffn

858

1484

859

@deffn Command raise-window window

1485

@deffn Function raise-window window

1486

@deffnx Command raise-single-window window

860

1487

Raise @var{window} to the top of its stacking depth.

861

1488

@end deffn

862

1489

863

@deffn Command raise-lower-window window

1490

@deffn Function raise-lower-window window

1491

@deffnx Command raise-lower-single-window window

864

1492

If @var{window} is the highest in its stacking level, lower it to the

865

1493

bottom of this level, otherwise raise it to the top of its level.

866

1494

@end deffn

867

1495

868

@deffn Command lower-window-depth window

1496

Notice how the function name and command name for each pair differs

1497

slightly. Another set of functions supports operating on multiple windows

1498

simultaneously. Again, the function name and command name for each

1499

pair is different.

1500

1501

@deffn Function lower-window* window

1502

@deffnx Command lower-window window

1503

Lower @var{window} and possibly associated windows to the bottom of

1504

their stacking depths.

1505

@end deffn

1506

1507

@deffn Function raise-window* window

1508

@deffnx Command raise-window window

1509

Raise @var{window} and possibly associated windows to the top of their

1510

stacking depth.

1511

@end deffn

1512

1513

@deffn Function raise-lower-window* window

1514

@deffnx Command raise-lower-window window

1515

If @var{window} is the highest in its stacking level, lower it and

1516

possibly associated windows to the bottom of their level, otherwise

1517

raise them to the top of their level.

1518

@end deffn

1519

1520

@defvar user-raise-type

1521

Indicates which windows the @code{lower-window*}, @code{raise-window*}

1522

and @code{raise-lower-window*} functions affect. This variable can be

1523

1524

@table @code

1525

@item none

1526

Only the specific argument window is affected.

1527

@item transients

1528

The specific argument window and all of its transients are affected.

1529

This is the default.

1530

@item group

1531

The specific argument window and all windows in its group are

1532

affected.

1533

@end table

1534

@end defvar

1535

1536

@defun maybe-raise-window w

1537

If window @var{w} supports the @code{_SAWFISH_WM_RAISE_WINDOW}

1538

protocol, ask it whether it wants to raise itself or not. Otherwise,

1539

raise the window unconditionally.

1540

@end defun

1541

1542

@defun maybe-lower-window w

1543

If window @var{w} supports the @code{_SAWFISH_WM_LOWER_WINDOW}

1544

protocol, ask it whether it wants to lower itself or not. Otherwise,

1545

lower the window unconditionally.

1546

@end defun

1547

1548

Sawfish has more general operations that raising a window to the top

1549

or lowering it to the bottom. It can place a window relative to one

1550

or more other managed windows.

1551

1552

@defun raise-windows w order

1553

@defunx lower-windows w order

1554

@defunx raise-lower-windows w order

1555

Raise (or lower) all windows in @var{order}, such that items earlier in

1556

the list are higher (or lower) than later items. The window @var{w}

1557

is special, always being the highest or lowest window, even if appears

1558

in the middle of @var{order}.

1559

1560

For @code{raise-lower-windows}, if @var{w} would be raised or lowered,

1561

then all the other windows are also raised or lowered.

1562

@end defun

1563

1564

There are also functions (and associated commands) to change a

1565

window's depth.

1566

1567

@deffn Function lower-window-depth window

1568

@deffnx Command lower-window-depth window

869

1569

Decrement the stacking depth of @var{window}.

870

1570

@end deffn

871

1571

872

@deffn Command raise-window-depth window

1572

@deffn Function raise-window-depth window

1573

@deffnx Command raise-window-depth window

873

1574

Increment the stacking depth of @var{window}.

874

1575

@end deffn

875

1576

1577

Sawfish provides special support for ``click-to-focus'' mode, where

1578

you may or may not want to raise the window or pass the click to the

1579

underlying application.

1580

1581

@defun raise-and-pass-through-click w

1582

Raise the window that received the current event with

1583

@code{maybe-raise-window}. Then replay any pointer events that

1584

invoked the command.

1585

@end defun

1586

1587

@defun raise-and-pass-through-click-if-focused w

1588

Raise the window that received the current event (if it's focused)

1589

with @code{maybe-raise-window}. Then replay any pointer events that

1590

invoked the command.

1591

@end defun

1592

1593

@defun raise-or-pass-through-click w

1594

If the window that received the current event is not on top, raise it

1595

with @code{maybe-raise-window}. Otherwise replay any pointer events

1596

that invoked the command, sending them to the window.

1597

@end defun

1598

1599

When the above commands are called interactively, Sawfish will try to

1600

invoke them on the window that received the current event. Failing

1601

that, Sawfish will invoke them on the currently focused window.

876

1602

877

1603

@node Moving and Resizing Windows, Showing and Hiding Windows, Window Stacking, Windows

878

1604

@section Moving and Resizing Windows

895

1621

@end defun

896

1622

897

1623

@defun move-resize-window-to window x y width height

898

A combination of the previous two functions.

1624

Move the top-left corner of the window frame of @var{window} to

1625

(@var{x}, @var{y}), and set the dimensions of the frame to

1626

(@var{width}, @var{height}).

899

1627

@end defun

900

1628

901

1629

@defun resize-window-with-hints window cols rows &optional hints

1630

@defunx resize-window-with-hints* window width height &optional hints

902

1631

Resize the window associated with object @var{window} so that it has

903

@var{cols} columns and @var{rows} rows. The @var{hints} parameters is

904

either the size hints alist to use, or @code{nil} in which case the

905

@code{window-size-hints} function is used to retrieve the window's

906

hints.

1632

certain X and Y dimensions. For the first function, the dimensions

1633

are @var{cols} columns and @var{rows} rows. For the second function,

1634

the dimensions are @var{width} pixels and @var{height} pixels.

1635

1636

The @var{hints} parameters is either the size hints alist to use, or

1637

@code{nil} in which case the @code{window-size-hints} function is used

1638

to retrieve the window's hints.

907

1639

@end defun

908

1640

909

1641

Usually, however, it is left to the user to configure windows. The

970

1702

The distance in pixels before snapping together two edges.

971

1703

@end defvar

972

1704

1705

Windows have a ``gravity'' property, which affect how they are placed

1706

in particular positions.

1707

1708

@defun window-gravity window &optional hints

1709

Returns the gravity of window. The order of precedence is Sawfish

1710

@code{gravity} window property, explicit @var{hints} argument, X

1711

window size hints. The default gravity when nothing else is specified

1712

is @code{north-west} (specified by ICCCM).

1713

@end defun

973

1714

974

1715

@node Showing and Hiding Windows, Destroying Windows, Moving and Resizing Windows, Windows

975

1716

@section Showing and Hiding Windows

982

1723

(@pxref{Workspaces}) and iconification (@pxref{Iconifying Windows}).

983

1724

984

1725

@defun hide-window window

985

Prevent object @var{window} from being displayed.

1726

Prevent object @var{window} from being displayed. See

1727

@code{show-window}.

986

1728

@end defun

987

1729

988

1730

@defun show-window window

989

1731

Ensure that @var{window} (if it has been mapped, and is within the

990

screen boundary) is visible.

1732

screen boundary) is visible. See @code{hide-window}.

991

1733

@end defun

992

1734

993

1735

@defun window-visible-p window

1039

1781

Many window managers allow a window to be @dfn{shaded}; when in this

1040

1782

state only the title bar of the window is visible.

1041

1783

1784

@defun window-shaded-p window

1785

Returns true when @var{window} is shaded, false otherwise.

1786

@end defun

1787

1042

1788

@deffn Command shade-window window

1043

1789

Arrange for only the title bar of @var{window} to be visible.

1044

1790

@end deffn

1051

1797

Toggle the shaded state of the window.

1052

1798

@end deffn

1053

1799

1800

@defvar raise-windows-when-unshaded nil

1801

When true, raise windows when they are unshaded. Defaults to false.

1802

@end defvar

1803

1054

1804

The @code{shaded} property of a window is set to @code{t} when the

1055

1805

window is shaded. If a window is added with this property already set,

1056

1806

then the window will appear in its shaded state.

1057

1807

1058

1808

1059

@node Iconifying Windows, Maximizing Windows, Shading Windows, Windows

1809

@node Iconifying Windows, Window Stickiness, Shading Windows, Windows

1060

1810

@section Iconifying Windows

1061

1811

@cindex Iconifying windows

1062

1812

@cindex Windows, iconifying

1074

1824

Return the window associated with @var{window} from its iconified state.

1075

1825

@end deffn

1076

1826

1827

@deffn Command toggle-window-iconified window

1828

Minimize the window associated with @var{window}, or restore it if it

1829

is already minimized.

1830

@end deffn

1831

1832

@deffn Command iconify-workspace-windows

1833

Minimize all windows in the current workspace.

1834

@end deffn

1835

1077

1836

A window's iconic state may be tested through examination of its

1078

1837

@code{iconified} property---when @code{t} the window is iconified.

1079

1080

1081

@node Maximizing Windows, , Iconifying Windows, Windows

1838

But it is preferable to use explicit testing functions instead:

1839

1840

@defun window-iconified-p window

1841

Returns true if the window associated with @var{window} is iconified,

1842

false otherwise.

1843

@end defun

1844

1845

@defun window-iconifiable-p window

1846

Returns true if the window associated with @var{window} can be

1847

iconified, false otherwise. Some reasons a window might not be

1848

iconifiable are: it has a @code{never-iconify} property; it is

1849

already iconified; it is not a desktop window; or it is marked

1850

@code{ignored} and @code{iconify-ignored} is not true.

1851

@end defun

1852

1853

@defvar iconify-ignored nil

1854

Unmanaged (@code{ignored}) windows may be iconified. Defaults to nil.

1855

@end defvar

1856

1857

Sawfish allows you to control certain behaviors when restoring

1858

minimized windows.

1859

1860

@defvar focus-windows-on-uniconify

1861

Windows are focused after being unminimized. Defaults to false.

1862

@end defvar

1863

1864

@defvar raise-windows-on-uniconify

1865

Windows are raised after being unminimized. Defaults to true.

1866

@end defvar

1867

1868

@defvar uniconify-to-current-workspace

1869

Move windows to the current workspace when they are unminimized.

1870

Defaults to true.

1871

@end defvar

1872

1873

When iconifying, it is possible to force other windows to iconify.

1874

1875

@defvr Customizable iconify-group-mode

1876

@defvrx Customizable uniconify-group-mode

1877

Policy for performing chains of minimizations or restorations. When a

1878

particular window is minimized or restored, it can cause other windows

1879

to be minimized or restored at the same time. Their allowed values

1880

are set to the following list. By default, both variables are bound

1881

to the symbol @code{transients}. but they are not required to have the

1882

same value.

1883

@end defvr

1884

1885

@table @code

1886

@item none

1887

No additional windows are minimized or restored.

1888

@item transients

1889

All transient windows associated with the target window are minimized

1890

or restored.

1891

@item group

1892

All windows in the target window's group are minimized or restored.

1893

@end table

1894

1895

Finally, it's possible to get the icon that would normally be

1896

displayed for an iconified window.

1897

1898

@defun window-icon-image window

1899

Return an image object representing the icon currently associated with

1900

@var{window}, or @code{nil} if there is no such image.

1901

@end defun

1902

1903

@node Window Stickiness, Ignored Windows, Iconifying Windows, Windows

1904

@section Window Stickiness

1905

@cindex Window stickiness

1906

@cindex Sticky, windows

1907

1908

Windows normally exist in a single workspace and a single viewport

1909

into that workspace. When changing workspace or viewport, the current

1910

windows disappear. This is sometimes not the correct policy; there

1911

are certain windows that should ``follow'' the user from window to

1912

window. These are typically windows that are not bound to a

1913

particular activity. The most common example is a dashboard window

1914

for calling other applications. Another example might be a diagnostic

1915

program such as a load monitory.

1916

1917

Each window has ``stickiness'' flags that govern this behavior. One

1918

flag controls stickiness across workspaces: sticky windows will appear

1919

in every workspace automatically. The other flag similarly governs

1920

stickiness across viewports. A window is ``sticky'' if either of

1921

these flags are set.

1922

1923

Sticky windows are often @code{ignored}, so they lack window

1924

decorations, and @code{avoid}ed so other windows do not cover them up.

1925

1926

@defun window-sticky-p/workspace window

1927

@defunx window-sticky-p/viewport window

1928

@defunx window-sticky-p window

1929

Returns true if @var{window} is sticky across a particular environment

1930

(workspaces, viewports, or either), false otherwise.

1931

@end defun

1932

1933

@defun make-window-sticky/workspace window

1934

@defunx make-window-sticky/viewport window

1935

@defunx make-window-sticky window

1936

Make the @var{window} sticky across some environment (workspaces,

1937

viewports, or both).

1938

@end defun

1939

1940

@defun make-window-unsticky/workspace window

1941

@defunx make-window-unsticky/viewport window

1942

@defunx make-window-unsticky window

1943

Make the @var{window} unsticky across some environment (workspaces,

1944

viewports or both).

1945

@end defun

1946

1947

@defun toggle-window-sticky window

1948

If @code{window-sticky-p} would report true for @var{window}, make

1949

@var{window} unsticky for all environments. Otherwise make it sticky

1950

for all environments.

1951

@end defun

1952

1953

@node Ignored Windows, Maximizing Windows, Window Stickiness, Windows

1954

@section Ignored Windows

1955

@cindex Windows, ignored

1956

1957

Sawfish has a general concept of ``ignored'' windows; the user does

1958

not interact normally with those windows. The concept is actually

1959

defined by five different window properties:

1960

1961

@table @code

1962

@item ignored

1963

The window does not receive frames.

1964

1965

@item never-focus

1966

The window never receives the input focus.

1967

1968

@item cycle-skip

1969

The window is ignored while window cycling.

1970

1971

@item window-list-skip

1972

The window will not be included in the window list.

1973

1974

@item task-list-skip

1975

The window will not be included in the task list.

1976

1977

@end table

1978

1979

A monitor application such as ``xload'' might have all five of these

1980

flags set.

1981

1982

Rather than directly manipulating the window properties, it is better

1983

to use the following access functions:

1984

1985

@defun window-ignored-p window

1986

Returns true if the window has the @code{ignored} property, false

1987

otherwise.

1988

@end defun

1989

1990

@deffn Command make-window-ignored window

1991

Ignore the window @var{window}.

1992

@end deffn

1993

1994

@deffn Command make-window-not-ignored window

1995

Unignore the window @var{window}.

1996

@end deffn

1997

1998

@deffn Command toggle-window-ignored window

1999

If @code{window-ignored-p} would return true for @var{window}, make it

2000

unignored. Otherwise make it ignored.

2001

@end deffn

2002

2003

The remaining flags only have toggle functions implemented right now:

2004

2005

@deffn Command toggle-window-never-focus window

2006

@deffnx Command toggle-window-cycle-skip window

2007

@deffnx Command toggle-window-list-skip window

2008

@deffnx Command toggle-task-list-skip window

2009

Toggle the appropriate flag on @var{window}.

2010

@end deffn

2011

2012

All five of the flags are available through the window menu's

2013

``Toggle'' entry.

2014

2015

@node Maximizing Windows, Animating Windows, Ignored Windows, Windows

1082

2016

@section Maximizing Windows

1083

2017

@cindex Maximizing windows

1084

2018

@cindex Windows, maximizing

1085

2019

1086

The dimensions of a window may be temporarily @dfn{maximized}.

2020

The dimensions of a window may be temporarily @dfn{maximized},

2021

stretching as far as possible across the screen in one or two

2022

dimensions.

1087

2023

1088

2024

@deffn Command maximize-window window &optional direction

1089

2025

Maximize both dimensions of @var{window}

1137

2073

Return @code{t} when @var{window} is horizontally maximized.

1138

2074

@end defun

1139

2075

2076

@node Animating Windows, Cycling Between Windows, Maximizing Windows, Windows

2077

@section Animating Windows

2078

@cindex Windows, Animating

2079

2080

Sawfish provides certain window animation capabilities. They have

2081

been described as ``lame'', so they are off by default.

2082

2083

@defvar default-window-animator

2084

The default window animation mode, used if a window has no explicit

2085

animation set. Normally @code{none}.

2086

@end defvar

2087

2088

@defun define-window-animator name fun

2089

Define a window animator called @var{name} (a symbol) that is managed

2090

by function @var{fun}. @var{fun} is called as @samp{(fun window op

2091

[action])} when it should change the state of an animation sequence.

2092

@var{Op} may be one of the symbols @code{start}, @code{stop}.

2093

@end defun

2094

2095

@defun autoload-window-animator name struct

2096

Construct an autoloader for window animator @var{name} from structure

2097

@var{struct}.

2098

@end defun

2099

2100

@defun run-window-animator window action

2101

Invoke an animation for action @var{action} on @var{window}.

2102

@var{Action} may be one of the symbols @code{start}, @code{stop}.

2103

@end defun

2104

2105

@defun record-window-animator window animator

2106

Note that @var{window} currently has an animation running, being

2107

controlled by animator function @var{animator}.

2108

@end defun

2109

2110

@node Cycling Between Windows, Window Groups, Animating Windows, Windows

2111

@section Cycling Between Windows

2112

@cindex Windows, cycling between

2113

2114

Sawfish provides two categories of commands for cycling between

2115

windows. The first category cycles between windows in an order that

2116

is essentially fixed. The second category cycles between windows in a

2117

dynamic order.

2118

2119

@menu

2120

* Fixed Window Cycles::

2121

* Dynamic Window Cycles::

2122

@end menu

2123

2124

@node Fixed Window Cycles, Dynamic Window Cycles, Cycling Between Windows, Cycling Between Windows

2125

@subsection Fixed Window Cycles

2126

@cindex Window cycles, fixed

2127

2128

These commands organize the set of mangaged windows into loops. A

2129

loop may consist of all windows in a workspace, or it may consist of

2130

all windows anywhere. The positions of windows in this loop do not

2131

change, except when a new window is managed or unmanaged.

2132

2133

@defun next-workspace-window

2134

@defunx previous-workspace-window

2135

Switch focus to the ``next'' or ``previous'' window in the current

2136

workspace.

2137

@end defun

2138

2139

@defun next-window

2140

@defunx previous-window

2141

Switch focus to the ``next'' or ``previous'' window in this

2142

workspace. If this function reaches the ``end'' of the windows in

2143

this workspace, it switches to the next workspace and displays the

2144

first window there.

2145

@end defun

2146

2147

@node Dynamic Window Cycles, , Fixed Window Cycles, Cycling Between Windows

2148

@subsection Dynamic Window Cycles

2149

@cindex Window cycles, dynamic

2150

2151

These commands implement something much close to Microsoft Windows'

2152

@key{Alt-TAB} mechanism, working with a stack of recently used

2153

windows.

2154

2155

@defun cycle-windows

2156

@defunx cycle-windows-backwards

2157

Cycle through all cycleable windows.

2158

@end defun

2159

2160

@defun cycle-group

2161

@defunx cycle-group-backwards

2162

Cycle through all windows in this group.

2163

2164

This is somewhat comparable to the @key{Control-TAB} behavior of

2165

windows.

2166

@end defun

2167

2168

@defun cycle-prefix

2169

@defunx cycle-prefix-backwards

2170

Cycle through all windows whose titles match that of the initial

2171

window (up to, but not including, the first colon).

2172

@end defun

2173

2174

@defun cycle-class

2175

@defunx cycle-class-backwards

2176

Cycle through all windows whose classes match that of the initial

2177

window.

2178

@end defun

2179

2180

@defun cycle-dock

2181

@defunx cycle-dock-backwards

2182

Cycle through all windows in the dock, even those with the

2183

@code{cycle-skip} property.

2184

@end defun

2185

2186

Each of these cycling commands may include windows that are not

2187

visible on-screen.

2188

2189

@defvar cycle-include-iconified

2190

If true, Sawfish includes iconified windows when cycling. Defaults to

2191

true.

2192

@end defvar

2193

2194

@defvar cycle-all-workspaces

2195

If true, Sawfish includes windows on all workspaces when cycling.

2196

Defaults to false.

2197

@end defvar

2198

2199

@c FIXME: viewports aren't documented right now

2200

@c @defvar cycle-all-viewports

2201

@c If true, Sawfish includes windows on all viewports when cycling.

2202

@c Defaults to false.

2203

@c @end defvar

2204

2205

It is possible to configure the cycling to get more feedback during

2206

the process.

2207

2208

@defvar cycle-show-window-names

2209

If true, Sawfish displays window names and icons while cycling through

2210

windows. Defaults to true.

2211

@end defvar

2212

2213

@defvar cycle-raise-windows t

2214

If true, Sawfish raises windows while they're temporarily selected

2215

during cycling. Defaults to true.

2216

@end defvar

2217

2218

It is also possible for you to define your own stacking cycle

2219

commands, or even to alter the window stack to suit your tastes.

2220

2221

@defun define-cycle-command name body &rest rest

2222

Create a command that will not cause the current cycle operation

2223

to abort before execution.

2224

2225

All arguments are passed to define-command.

2226

@end defun

2227

2228

@defun define-cycle-command-pair forward-name reverse-name selector &rest rest

2229

Create a pair of commands for cycling through windows. The command named

2230

@var{forward-name} cycles forwards, while the command named

2231

@var{reverse-name} cycles backwards.

2232

2233

@var{Selector} is called when initializing the cycle environment, it

2234

should return the list of windows to cycle through, or the symbol `t'

2235

to denote all cyclable windows.

2236

2237

Any extra arguments are passed to each call to define-command.

2238

@end defun

2239

2240

@defun window-order &optional workspace allow-iconified all-viewports

2241

Return managed windows in most-recently used order.

2242

2243

If @var{workspace} is non-nil, then only managed windows in that

2244

workspace will be returned.

2245

2246

If @var{allow-iconified} is non-nil, then iconified windows will be

2247

returned instead of ignored.

2248

2249

If @var{all-viewports} is non-nil, then windows in all viewports will

2250

be returned, instead of just the current viewport.

2251

@end defun

2252

2253

@defun window-order-push w

2254

Push window @var{w} onto the top of the cycle stack.

2255

@end defun

2256

2257

@defun window-order-pop w

2258

Remove window @var{w} from the cycle stack.

2259

@end defun

2260

2261

@defun window-order-most-recent &key windows

2262

Return the most-recently focused window in the current workspace. If

2263

the @var{windows} argument is given it should be a list of windows, in

2264

this case the function will restrict its search to the elements of

2265

this list.

2266

@end defun

2267

2268

@defun window-order-focus-most-recent

2269

Switch input focus to the most-recently focused window in the current

2270

workspace.

2271

@end defun

2272

2273

@node Window Groups, , Cycling Between Windows, Windows

2274

@section Window Groups

2275

@cindex Groups, windows

2276

2277

Sawfish provides extra tools and commands for dealing with ICCCM

2278

groups. Most ``normal'' groups work the same way as they do in the

2279

ICCCM standard: windows have a group property that is set to the X

2280

window ID of the group leader. These are ``group IDs'', and they are

2281

always positive integers. In addition, Sawfish allows group IDs to

2282

be:

2283

2284

@table @asis

2285

@item negative integers

2286

These are anonymous user-defined groups.

2287

@item symbols

2288

These are named user-defined groups. Named user-defined groups are

2289

saved as part of window properties when saving sessions.

2290

@end table

2291

2292

@defun window-group-ids

2293

Return the list of all group ids.

2294

@end defun

2295

2296

There may be certain named groups that always exist, whether or not

2297

any window belongs to them.

2298

2299

@defvar peristent-group-ids

2300

A list of symbols naming groups that always exist.

2301

@end defvar

2302

2303

In any case, a window is limited to belonging to one group, and always

2304

belongs to one group.

2305

2306

@menu

2307

* Assigning Windows to Groups::

2308

* Operations on Groups::

2309

@end menu

2310

2311

@node Assigning Windows to Groups, Operations on Groups, Window Groups, Window Groups

2312

@subsection Assigning Windows to Groups

2313

@cindex Groups, assigning windows to

2314

2315

It is possible to change the group of a window in Sawfish. Use

2316

@code{add-window-to-group}, or if necessary you can set the window's

2317

@code{group} property explicitly.

2318

2319

@defun add-window-to-group window group-id

2320

Place @var{window} in group @var{group-id}, replacing any previous

2321

group membership. If @var{group-id} is @code{nil}, then Sawfish

2322

returns the window to whatever group membership was supplied by ICCCM.

2323

@end defun

2324

2325

@defun add-window-to-new-group window

2326

Place @var{window} into a new group, which will have @var{window} as

2327

its sole member. This is an anonymous user-defined group. The new

2328

group ID is returned.

2329

@end defun

2330

2331

The Sawfish group assignment never overrides the ICCCM group

2332

assignment, just suppresses it. The @code{window-actual-group-id}

2333

function implements this overriding.

2334

2335

@defun window-actual-group-id window

2336

Return the (Sawfish) group ID for @var{window}. This is, in order of

2337

preference:

2338

@itemize @bullet

2339

@item The group ID assigned by Sawfish

2340

@item The group ID passed in by ICCCM.

2341

@item The corresponding values for an owning window, if the given window is transient.

2342

@item The window's own window ID.

2343

@end itemize

2344

2345

This means that a window is, at the very least, part of its own group.

2346

@end defun

2347

2348

Each of the following functions operates on the ``actual group ID'' as

2349

returned by the above function.

2350

2351

@defun windows-by-group group-id &optional by-depth

2352

Return the list of windows in the group with id @var{group-id}.

2353

If @var{by-depth} is non-nil, then return the windows in order of

2354

stacking, from topmost to bottommost.

2355

@end defun

2356

2357

@defun windows-in-group w &optional by-depth

2358

Return the list of windows in the same group as window @var{w}.

2359

If @var{by-depth} is non-nil, then return the windows in order of

2360

stacking, from topmost to bottommost.

2361

@end defun

2362

2363

@defun map-window-group fun w

2364

Map the single argument function @var{fun} over all windows in the

2365

same group as window @var{w}. Note that @var{fun} needs to operate

2366

using side-effects, rather than returning values.

2367

@end defun

2368

2369

@defun map-other-window-groups fun w

2370

Map the single argument function @var{fun} over all windows not in the

2371

same group as window @var{w}. Note that @var{fun} needs to operate

2372

using side-effects, rather than returning values.

2373

@end defun

2374

2375

@defun window-group-menu &optional w

2376

Return a menu definition suitable for @code{popup-menu}. This menu

2377

will allow the user to assign the window @var{w} into any group of a

2378

managed window, or into a brand new group. The window's current group

2379

is checked or otherwise marked.

2380

@end defun

2381

2382

@node Operations on Groups, , Assigning Windows to Groups, Window Groups

2383

@subsection Operations on Groups

2384

@cindex Groups, operations on

2385

2386

Most of the window manipulation functions that operate on windows are

2387

also available for window groups. Each of these functions takes a

2388

window as argument; the affected group is that window's group.

2389

2390

@defun iconify-group w

2391

@defunx uniconify-group w

2392

@defunx iconify-transient-group w

2393

@defunx uniconify-transient-group w

2394

These operate like their single-window counterparts. They work by

2395

temporarily rebinding @code{iconify-group-mode} and

2396

@code{uniconify-group-mode}.

2397

@end defun

2398

2399

@defun make-group-sticky w

2400

@defunx make-group-unsticky w

2401

These operate like their single-window counterparts.

2402

@end defun

2403

2404

@defun toggle-group-sticky w

2405

If window @var{w} is sticky, all windows in its group have their

2406

stickyness removed. Otherwise all windows in its group become sticky.

2407

@end defun

2408

2409

@defun send-group-to-workspace w workspace

2410

@defunx send-group-to-next-workspace w count

2411

@defunx send-group-to-previous-workspace w count

2412

These operate like their single-window counterparts.

2413

@end defun

2414

2415

@defun send-group-to-current-workspace w

2416

All windows in the group of @var{w} are moved from their existing

2417

workspaces to the nearest workspace that @var{w} is in. Sticky

2418

windows are not affected. If the window had the input focus and it is

2419

visible after the move, it retains the input focus.

2420

@end defun

2421

2422

@c FIXME: viewports are deprecated, so this is commented out

2423

@c @defun move-group-to-current-viewport w

2424

@c @defunx move-group-viewport w

2425

@c @end defun

2426

2427

@defun move-group-left w

2428

@defunx move-group-right w

2429

@defunx move-group-up w

2430

@defunx move-group-down w

2431

These operate like their single-window counterparts.

2432

@end defun

2433

2434

@defun raise-group w

2435

@defunx lower-group w

2436

@defunx raise-lower-group w

2437

@defunx raise-group-depth w

2438

@defunx lower-group-depth w

2439

These operate like their single-window counterparts.

2440

@end defun

2441

2442

@defun set-group-frame-style w style

2443

This operates like its single-window counterpart.

2444

@end defun

1140

2445

1141

2446

@node Customization, Window Frames, Windows, Top

1142

2447

@chapter Customization

1175

2480

macro must be used. This augments the variable with extra information

1176

2481

for the GUI, including such things as its required data type.

1177

2482

1178

Customization options are organized into groups. Each group has a name

1179

and contains a set of related options. Currently, it is not possible

1180

for groups to contain sub-groups.

2483

@menu

2484

* Defgroup and Defcustom::

2485

* Customization Files::

2486

* Customized Variable Status::

2487

@end menu

2488

2489

@node Defgroup and Defcustom, Customization Files, Customization, Customization

2490

@section Defgroup and Defcustom

2491

@cindex defgroup

2492

@cindex defcustom

2493

2494

Customization options are organized into groups. Each group has a name

2495

and contains a set of related options. Groups can be assigned to

2496

parent groups using the @code{:group} parameter during construction.

1181

2497

1182

2498

@defmac defgroup group real-name &rest keys

1183

2499

Declares a new customization group whose name is defined by the symbol

1186

2502

1187

2503

@var{keys} is a list, defining the properties of the group. The members

1188

2504

of the list are grouped into pairs of elements, the first element names

1189

the property, the second defines its value. Currently the only property

1190

is @code{:widget}, defining a function to create the group's UI widget.

2505

the property, the second defines its value.

2506

2507

@table @code

2508

@item :group @var{group}

2509

Specifies the parent customization group of this group. The value of

2510

this key is not evaluated.

2511

2512

@item :require @var{struct}

2513

Before displaying the customization UI for this group, @code{require}

2514

the structure @var{struct}. This guarantees that all customizable

2515

variables will be known at display time. The value of

2516

this key is not evaluated.

2517

2518

@item :layout @var{symbol}

2519

Use a particular UI widget to display this group. The value is a

2520

symbol, one of:

2521

2522

@table @code

2523

@item single

2524

Holds a single customizable item.

2525

@item vbox

2526

Holds any number of customizable items, arranging them vertically.

2527

This is the default.

2528

@item hbox

2529

Holds any number of customizable items, arranging them horizontally.

2530

@item frame

2531

Embed the items in a vbox in a frame.

2532

@item keymaps

2533

Use a special UI widget for customizing keymaps.

2534

@end table

2535

2536

The value of this key is not evaluated.

2537

@end table

1191

2538

1192

2539

This macro also creates an interactive function named

1193

2540

@code{customize:@var{group}} allowing the GUI to be invoked to

1194

2541

configure the new group.

2542

2543

While @code{defgroup} is a macro, there is a corresponding

2544

@code{custom-declare-group} function.

1195

2545

@end defmac

1196

2546

1197

2547

@defmac defcustom variable value documentation &rest keys

1206

2556

@table @code

1207

2557

@item :group @var{group}

1208

2558

Specifies the customization group that this variable is a member of.

2559

This is a list of symbols, indicating a series of nested groups, e.g.,

2560

@code{(workspace edge-flip)}. A variable in a top-level customization

2561

group can also be specified as a plain symbol, e.g., @code{workspace}.

2562

The value of this key is not evaluated.

1209

2563

1210

2564

@item :type @var{type}

1211

2565

Specifies the required type of the variable. The current possibilities

1212

are @code{boolean}, @code{number}, @code{string}, @code{file-name},

1213

@code{program-name}, @code{font}, @code{color}, @code{frame-style},

1214

@code{keymap} and @code{(set @var{symbols}@dots{})}.

1215

1216

The @code{boolean} type assures a value of either @code{nil} or

1217

@code{t}, the @code{set} type allows the user to choose from one of the

1218

symbols in the list.

1219

2566

are:

2567

2568

@item @code{(symbol [@var{option} @dots{}])}

2569

A symbol. The UI looks for a symbol property @code{:options} and

2570

interprets it as the list of valid symbols to select from. The

2571

@var{option} arguments allow you to define a list at eval time. It is

2572

also possible to change this list at run time by changing the custom

2573

symbol's @code{:options} property; see the access functions

2574

@code{custom-add-options} and @code{custom-set-options} for more

2575

information.

2576

2577

@item @code{(choice @var{option} @dots{})}

2578

One of the @var{option} elements. Each @var{option} is a symbol.

2579

Unlike the @code{symbol} type, there is no expectation that this list

2580

will change at run-time.

2581

2582

@item @code{string}

2583

An arbitrary string.

2584

2585

@item @code{(number [[@var{min}] @var{max}]}

2586

Integer number. Two additional arguments specify the minimum and

2587

maximum allowed values for the integer. One additional argument

2588

specified the maximum allowed value; the minimum defaults to zero.

2589

Zero additional arguments implies no minimum nor maximum.

2590

2591

@item @code{boolean}

2592

True (@code{t}) or false (@code{nil}) value.

2593

2594

@item @code{color}

2595

A color.

2596

2597

@item @code{font}

2598

A font name.

2599

2600

@item @code{file}

2601

A file name.

2602

2603

@item @code{program}

2604

A file name that must be an executable program.

2605

2606

@item @code{command}

2607

A Sawfish command.

2608

2609

@item @code{event}

2610

A Sawfish event.

2611

2612

@item @code{keymap}

2613

A Sawfish keymap.

2614

2615

@item @code{frame-style}

2616

The name of a defined Sawfish frame style.

2617

2618

@item @code{icon}

2619

An X icon.

2620

2621

@item @code{modifier-list}

2622

A list of X modifier keys.

2623

2624

@c @item @code{workspace-geometry}

2625

@c A @code{(@var{columns} . @var{rows})} pair.

2626

2627

@end table

2628

2629

Except where specified, the values of these keys are not evaluated.

2630

2631

@table @code

1220

2632

@item :require @var{feature}

1221

2633

Denotes that the feature @var{feature} must be loaded if the variable

1222

is set to a non-@code{nil} value by user customizations. This is

2634

is set to a non-@code{nil} value by user customizations. This is

1223

2635

necessary because customization options are loaded on startup, possibly

1224

2636

before the modules that define them.

2637

The value of this key is not evaluated.

1225

2638

1226

2639

@item :allow-nil @var{bool}

1227

2640

Specifies whether the variable may be @code{nil}, instead of a member

1228

2641

of its actual type. This is only supported by the @code{string},

1229

@code{set}, @code{font} and @code{color} types.

2642

@code{symbol}, @code{font} and @code{color} types.

1230

2643

1231

2644

@item :set @var{function}

1232

2645

Specifies that the variable must be set by calling @var{function}

1251

2664

the variable. Called with a single parameter: the variable itself.

1252

2665

1253

2666

@item :range (@var{min} . @var{max})

1254

The allowed range for numeric variables. If @var{min} is @code{nil} the

2667

The allowed range for numeric variables. If @var{min} is @code{nil} the

1255

2668

the default minimum allowed value is zero; if @var{max} is @code{nil}

1256

then the default maximum is unbounded.

2669

then the default maximum is unbounded. This is obsolete, since the

2670

@code{:number} type now supports range declarations.

2671

The value of this key is not evaluated.

2672

2673

@item :tooltop @var{string}

2674

A tooltip that appears when the user's mouse hovers over the widget

2675

item.

2676

2677

@item :depends @var{symbol}

2678

This widget item is only settable when the symbol-value for

2679

@var{symbol} is non-nil.

1257

2680

1258

2681

@end table

2682

2683

While @code{defcustom} is a macro, there is a corresponding

2684

@code{custom-declare-variable} function.

1259

2685

@end defmac

1260

2686

1261

2687

Note that where necessary the types themselves define default

1276

2702

(defcustom move-snap-epsilon 8

1277

2703

"Proximity in pixels before snapping to a window edge."

1278

2704

:group move

1279

:type number

1280

:range (0 . 64))

2705

:type (number 0 64))

1281

2706

@end lisp

1282

2707

1283

2708

@noindent

1284

2709

This defines a group and two customization options.

1285

2710

2711

There are two special accessor functions to make it easier to deal

2712

with lists of allowed symbols.

2713

2714

@defun custom-add-option variable option

2715

Add symbol value @var{option} to the list of symbols that can be

2716

stored in @var{variable}. The new option goes on the end of the

2717

list.

2718

@end defun

2719

2720

@defun custom-get-options variable

2721

Return the list of symbols that can be stored in @var{variable}.

2722

@end defun

2723

2724

@node Customization Files, Customized Variable Status, Defgroup and Defcustom, Customization

2725

@section Customization Files

2726

@cindex Customization files

2727

@cindex Files, customization

2728

2729

@defvar custom-user-file

2730

User configuration settings are stored in the file referenced by this

2731

variable. While this file contains valid Rep forms, users should not

2732

edit it directly: Sawfish will overwrite the file's contents each time

2733

a customization is made through the GUI.

2734

2735

By default, this variable is set to @code{"~/.sawfish/custom"}. The

2736

@code{--custom-file} command-line option sets it to a different file

2737

on program startup.

2738

@end defvar

2739

2740

@defvar custom-default-file

2741

Default customization settings are stored in the file referenced by

2742

this variable. These settings are only applied if the user has no

2743

personal settings. By default, this variable is set to

2744

@code{"sawfish/wm/custom-defaults.jl"} relative to the

2745

@code{sawfish-lisp-lib-directory} directory.

2746

@end defvar

2747

2748

@defun custom-load-user-file

2749

If the file referenced by @code{custom-user-file} exists, load it.

2750

Otherwise if @code{custom-default-file} is non-nil, interpret it as a

2751

filename and load it.

2752

@end defun

2753

2754

@node Customized Variable Status, , Customization Files, Customization

2755

@section Customized Variable Status

2756

2757

To get information about a customizable variable, you can use the

2758

following functions.

2759

2760

@defun variable-customized-p symbol

2761

Returns true if @var{symbol} has been customized by the user, false

2762

otherwise.

2763

@end defun

2764

2765

@defun variable-declared-p symbol

2766

@defunx variable-default-value symbol

2767

The @code{variable-declared-p} function returns true if the variable

2768

named @var{symbol} has a default value declared for it, false

2769

otherwise. The @code{variable-default-value} function returns the

2770

default value of that variable, or nil if no such default value

2771

exists.

2772

@end defun

2773

2774

@defun variable-type symbol

2775

Returns the customizable type of the variable named @var{symbol}.

2776

@end defun

1286

2777

1287

2778

@node Window Frames, Workspaces, Customization, Top

1288

2779

@chapter Window Frames

1394

2885

If @var{binding-forms} are given, they will be evaluated when no keymap

1395

2886

already exists for the class. A keymap will be created, and stored in

1396

2887

the variable named @samp{@var{class}-name}. This variable may then be

1397

used withing the @var{binding-forms}.

2888

used within the @var{binding-forms}.

1398

2889

@end defmac

1399

2890

1400

2891

So to define a hypothetical @code{shade-button} class, the following

1410

2901

frame part properties. For example, it might be your preference that

1411

2902

text in window title bars is always blue.

1412

2903

2904

@defun define-frame-class class alist-form &optional with-keymap

2905

Creates a new frame part class named by the symbol @var{class}.

2906

2907

Unlike @code{def-frame-class}, the trailing argument is just a boolean

2908

flag. This flag only indicates whether to create a keymap for the

2909

class. Any bindings have to be established through a separate call to

2910

@code{bind-keys}.

2911

2912

The function returns @code{t} if it was able to create and bind the

2913

empty keymap, @code{nil} otherwise. This allows us to check for

2914

errors.

2915

@end defun

2916

1413

2917

@defvar override-frame-part-classes

1414

2918

Similar to @code{frame-part-classes} except that the properties take

1415

2919

precedence over values defined both in that variable and in the frame

1610

3114

complete list of definitions (including inherited or overrided

1611

3115

definitions).

1612

3116

1613

@defun frame-part-get window class attr

1614

Returns the value of the attribute @var{attr} for the frame part of

1615

class @var{class} in the current frame of @var{window}.

1616

1617

Returns @code{nil} if no such attribute exists. If more than one frame

1618

part of class @var{class} exists then the value will be taken from the

1619

first part found.

3117

@defun frame-part-get part property

3118

Returns the value of the property @var{property} for the frame part

3119

object @var{part}. Returns @code{nil} if no such attribute exists.

3120

@end defun

3121

3122

@defun frame-part-put part prop value

3123

Set the property @var{prop} of frame part @var{part} to @var{value}.

3124

@end defun

3125

3126

@defun frame-part-state part

3127

Return the current state for frame part @var{part}, one of the symbols

3128

@code{focused}, @code{highlighted}, @code{clicked},

3129

@code{inactive-highlighted}, @code{inactive-clicked}, or @code{nil} if

3130

the part is inactive.

1620

3131

@end defun

1621

3132

1622

3133

@node Frame Functions, Frame Types, Frame Part Definition, Window Frames

1641

3152

created by the window manager.

1642

3153

@end defun

1643

3154

3155

@defun refresh-window window

3156

Refresh all the frame parts belonging to @var{window}.

3157

@end defun

3158

1644

3159

@defun rebuild-frame window

1645

3160

Recreates the window frame associated with @var{window}, from the

1646

3161

previously defined frame definition. All frame parts are reinitialized

1662

3177

origin of its frame.

1663

3178

@end defun

1664

3179

3180

@defun window-border-width window

3181

Return the width of the border of the window that @var{window}

3182

manages.

3183

@end defun

3184

3185

@defun clicked-frame-part

3186

Return a pointer to the frame part object that was clicked on as part

3187

of the current event. Returns @code{nil} if no frame part was clicked

3188

on.

3189

@end defun

3190

3191

@defun frame-part-dimensions part

3192

Return a cons cell @code{(@var{width} . @var{height})} of dimensions

3193

for frame part @var{part}.

3194

@end defun

3195

3196

@defun frame-part-position part

3197

Return a cons cell @code{(@var{x} . @var{x})} of the @emph{relative}

3198

position of frame part @var{part} against its window's frame

3199

origin.

3200

@end defun

3201

3202

@defun frame-part-window part

3203

Return the window object associated with this frame part.

3204

@end defun

3205

3206

@defun frame-part-x-window part

3207

Return the X11 window ID associated with this frame part.

3208

@end defun

3209

3210

@defun frame-draw-mutex lock

3211

Called with @var{lock} equal to @code{t}, frame part redraws will be

3212

delayed. The redraws will take place once the function is called with

3213

@var{lock} set to @code{nil}.

3214

@end defun

3215

3216

@defun map-frame-parts function window

3217

Call @code{(@var{function} @var{part})} on each the frame parts of

3218

@var{window} and return @code{nil}. If any @var{function} returns

3219

@code{nil}, @code{map-frame-parts} returns @code{nil} immediately.

3220

@end defun

3221

3222

@defun rebuild-frame-part part

3223

Build a new copy of the frame part @var{part} and install the copy in

3224

the owning window, replacing the old part.

3225

@end defun

3226

3227

@defun refresh-frame-part part

3228

The frame part @var{part} will be redrawn at the next opportunity.

3229

@end defun

3230

1665

3231

1666

3232

@node Frame Types, Frame Styles, Frame Functions, Window Frames

1667

3233

@section Frame Types

1669

3235

@cindex Window frames, types

1670

3236

1671

3237

In order to visually differentiate between different types of windows,

1672

several predefined types of window frame exist. These types currently

1673

include the following:

3238

several predefined types of window frame exist.

3239

3240

@defun window-type window

3241

Returns a symbol naming the frame type currently associated with

3242

@var{window}.

3243

@end defun

3244

3245

These frame types currently include the following:

1674

3246

1675

3247

@table @code

1676

3248

@item default

1702

3274

this frame type.

1703

3275

@end table

1704

3276

1705

The type of frame that would ideally be given to a window is stored in

1706

the window's @code{type} property. It should usually be accessed

1707

through the @code{window-type} function:

1708

1709

@defun window-type window

1710

Returns a symbol naming the frame type currently associated with

1711

@var{window}.

1712

@end defun

1713

3277

@defun define-frame-type-mapper fun

3278

Function @var{fun} maps from @{@var{window}, @var{frame-type}@} to

3279

@var{frame-type}.

3280

3281

Each time we want to determine a window's frame-type (@code{shaded},

3282

@code{transient}, etc.), we calculate an initial frame type with

3283

@code{window-type} and run the results through each frame type mapper

3284

in sequence (most recent to oldest). The frame type returned from the

3285

final mapper function is ``the'' frame type.

3286

3287

This sequence of mappers allows us to override window frame types

3288

based on window properties. For example, any shaded window has to

3289

have @code{shaded} or @code{shaded-transient} type, regardless of what

3290

its normal type is.

3291

@end defun

3292

3293

@defun window-type-add-border type

3294

@defunx window-type-add-title type

3295

@defunx window-type-remove-border type

3296

@defunx window-type-remove-title type

3297

Given a window type of @var{type}, return the closest matching window

3298

type with the given property change. For example:

3299

3300

@lisp

3301

(window-type-add-title 'unframed)

3302

@result{} 'shaped

3303

@end lisp

3304

3305

@noindent

3306

This is because shaped windows normally have title bars but not

3307

borders, while unframed windows normally have neither.

3308

@end defun

3309

3310

@defun frame-type-menu window

3311

Returns a list of frame types, suitable for use by the graphical

3312

customizer. The frame type of @var{window} is automatically checked.

3313

@end defun

3314

3315

We provide a function to simplify monitoring of window changes to certain

3316

window states. This monitoring runs on top of the

3317

@code{window-state-change-hook}.

3318

3319

@defun call-after-state-changed states fun

3320

Arrange for function @var{fun} to be called with arguments

3321

@samp{(window changed-states)} when one of the states defined by the

3322

list of symbols @var{states} has been changed. @var{States} may also

3323

be a single symbol.

3324

@end defun

1714

3325

1715

3326

@node Frame Styles, Themes, Frame Types, Window Frames

1716

3327

@section Frame Styles

1723

3334

with a function that creates a frame definition for a particular window

1724

3335

and frame type combination.

1725

3336

1726

@defun add-frame-style name function

1727

Defines a new frame style called @var{name} (a symbol). When a frame of

1728

this style is required for a particular window, @var{function} is

1729

called with two arguments, the window itself and a symbol defining the

1730

frame type to create (@pxref{Frame Types}).

1731

1732

If the frame style is unable to provide a frame definition of the

1733

required type, it should return the symbol @code{nil}. In which case it

1734

may subsequently be asked for a frame of a different type.

1735

1736

If no default frame style exists, the new style will be made the

1737

default.

1738

@end defun

1739

1740

@defvar default-frame-style

1741

A symbol naming the frame style to use for windows where no other style

1742

is explicitly specified.

1743

@end defvar

1744

1745

@defun check-frame-availability name

1746

Returns @code{t} if a frame style called @var{name} exists. Will try to

1747

load such a frame from the filing system if necessary.

1748

@end defun

1749

1750

@defun set-window-frame-style window style &optional type from-user

1751

Sets the frame of @var{window} to the style named by the symbol

1752

@var{style}. If @var{type} is defined then it names the frame type to

1753

use, otherwise the default type for this window is used.

1754

1755

If @var{from-user} is non-nil then the user chose this frame style for

1756

the window explicitly (i.e. it's not just the default choice for a new

1757

window).

1758

@end defun

1759

1760

@defun set-frame-for-window window &optional force type

1761

If @var{window} has no frame style associated with it, then chooses the

1762

default value for this window, the value of @code{default-frame-style}.

1763

1764

If @var{force} is non-nil then the style is always re-chosen, even if

1765

the window already has a chosen default style.

1766

1767

If @var{type} is non-nil it defines the frame type to give the window,

1768

otherwise the current default for the window is used.

1769

@end defun

1770

1771

@defun reframe-all-windows

1772

Forcibly reselect all window frame styles. Only windows with a user

1773

specified style are not changed to the current defaults.

1774

@end defun

1775

1776

@defun rebuild-frames-with-style style

1777

Call @code{rebuild-frame} on all windows that currently have a frame

1778

defined by frame style @var{style} (a symbol)

1779

@end defun

1780

1781

@defun reframe-windows-with-style style

1782

Completely recreate all window frames that are defined by the style

1783

@var{style}.

1784

@end defun

1785

1786

3337

Several window properties are used while choosing frame styles:

1787

3338

1788

3339

@defvr {Window Property} frame-style

1789

The user-chosen frame style of the window, or @code{nil}.

3340

The user-chosen frame style of the window. If @code{nil}, Sawfish

3341

will use the default frame style.

1790

3342

@end defvr

1791

3343

1792

3344

@defvr {Window Property} current-frame-style

1793

The current frame style of the window.

3345

The current frame style of the window. This is not set explicitly;

3346

window update functions will change it behind the scenes.

1794

3347

@end defvr

1795

3348

1796

3349

@defvr {Window Property} ignored

1797

3350

When set, the window is not given a frame.

1798

3351

@end defvr

1799

3352

3353

It is possible to edit certain frame styles in place with

3354

@code{sawfish-themer}.

3355

3356

@defun frame-style-editable-p style

3357

Returns @code{t} if @var{style} can be edited interactively,

3358

@code{nil} otherwise.

3359

@end defun

3360

3361

@deffn {Command} edit-frame-style style

3362

Prompts for a frame style (defaulting to the value of @code{default-frame-style}),

3363

and runs @code{sawfish-themer-program} on it.

3364

@end deffn

3365

3366

@defun reload-frame-style name

3367

Reloads the frame style @var{name} from disk if it is already known to

3368

the system. All windows with that style are reframed.

3369

@end defun

1800

3370

1801

3371

@node Themes, Removing Frame Parts, Frame Styles, Window Frames

1802

3372

@section Themes

1856

3426

@end defvar

1857

3427

1858

3428

@defvar system-theme-directory

1859

The name of the system theme directory.

1860

@end defvar

1861

1862

1863

@node Removing Frame Parts, , Themes, Window Frames

3429

The name of the directory holding themes from the current Sawfish

3430

version, by default

3431

@lisp

3432

(expand-file-name "../themes" sawfish-lisp-lib-directory)

3433

@end lisp

3434

@end defvar

3435

3436

@defvar site-theme-directory

3437

The name of the directory holding system-wide themes, by default

3438

@lisp

3439

(expand-file-name "../../themes" sawfish-lisp-lib-directory)

3440

@end lisp

3441

@end defvar

3442

3443

@defvar theme-update-interval

3444

Number of seconds between checking if theme files have been modified.

3445

Default 60.

3446

@end defvar

3447

3448

@defvar themes-are-gaoled

3449

If @code{t}, non-nil themes are assumed to be malicious. They will be

3450

evaluated in a restricted environment.

3451

@end defvar

3452

3453

@node Removing Frame Parts, , Themes, Window Frames

1864

3454

@section Removing Frame Parts

1865

3455

@cindex Removing frame parts

1866

3456

@cindex Frame parts, removing

1873

3463

However, not all frame styles will support this (it depends on the

1874

3464

frame part's @code{removable} property, @ref{Frame Part Definition}).

1875

3465

3466

@defun add-frame-class window class

3467

Enable all frame parts that are a member of @var{class} in

3468

@var{window}.

3469

@end defun

3470

3471

@defun frame-class-removed-p window class

3472

Returns @code{t} if the frame part @var{class} has been removed from

3473

@var{window}, @code{nil} otherwise.

3474

@end defun

3475

1876

3476

@defun remove-frame-class window class

1877

3477

Disable all frame parts that are a member of @var{class} in

1878

3478

@var{window} where possible.

1879

3479

@end defun

1880

3480

1881

@defun add-frame-class window class

1882

Enable all frame parts that are a member of @var{class} in

1883

@var{window}.

1884

@end defun

1885

1886

1887

@node Workspaces, Popup Menus, Window Frames, Top

3481

@c @node Viewports, Workspaces, Window Frames, Top

3482

@c @chapter Viewports

3483

@c @cindex Viewports

3484

@c

3485

@c It is sometimes useful to have a logical display that is larger than

3486

@c the computer screen. This is most often implemented by displaying

3487

@c only a portion of the logical display at any time. Sawfish does this

3488

@c using ``viewports''.

3489

@c

3490

@c When viewports are enabled, the Sawfish logical display becomes

3491

@c infinitely large in the two directions ``across'' and ``down'' (to the

3492

@c maximum representable size of integers). Sawfish divides this logical

3493

@c display into a potentially infinite grid of cells. Each cell of the

3494

@c grid is the same size of the virtual display.

3495

@c

3496

@c @defvar viewport-dimensions

3497

@c The current number of viewports across and down the virtual display.

3498

@c This is a cons cell @code{(@var{across} . @var{down})}. Defaults to

3499

@c @code{(1 . 1)}.

3500

@c @end defvar

3501

@c

3502

@c @defun set-number-of-viewports width height

3503

@c Change @code{viewport-dimensions} to have the value

3504

@c @code{(@var{width} . @var{height})}.

3505

@c @end defun

3506

@c

3507

@c The user then tells Sawfish to move the physical display from cell to

3508

@c cell. On a cell change, windows in previous cells are removed, and

3509

@c windows in the current cell appear. Windows that span two or more

3510

@c cells will appear in each cell, appropriately displaced.

3511

@c

3512

@c Note that cell indices start at zero in each dimension. Indices are

3513

@c never negative.

3514

@c

3515

@c @defun screen-viewport

3516

@c Returns the currently displayed viewport as a pair @code{(@var{x},

3517

@c @var{y})}.

3518

@c @end defun

3519

@c

3520

@c @defun set-screen-viewport col row

3521

@c Change the physical display to view cell @code{(@var{col},

3522

@c @var{row})}.

3523

@c @end defun

3524

@c

3525

@c @defun move-viewport right down

3526

@c Move the viewport to see the cell @var{right} slots to the right and

3527

@c @var{down} slots down. Either argument may be zero or negative.

3528

@c @end defun

3529

@c

3530

@c @defun set-window-viewport window col row

3531

@c Move @var{window} to the cell at @code{(@var{col}, @var{row})}. The

3532

@c relative position of the window within the cells is preserved.

3533

@c @end defun

3534

@c

3535

@c @defun move-window-viewport window col-delta row-delta

3536

@c Move @var{window} to the cell @var{col-delta} positions across and

3537

@c @var{row-delta} positions down from its current cell. The relative

3538

@c position of the window with its cells its preserved.

3539

@c @end defun

3540

@c

3541

@c @defun move-viewport-to-window window

3542

@c Move the viewport to a cell that shows window @var{window}. For a

3543

@c window that spans multiple cells, this function will pick the cell

3544

@c showing the window's top-left corner.

3545

@c @end defun

3546

@c

3547

@c @defun move-window-to-current-viewport window

3548

@c Move @var{window} from its existing viewport to the current viewport.

3549

@c The window's relative position in the existing viewport is preserved

3550

@c after the move.

3551

@c @end defun

3552

@c

3553

@c @defun window-viewport window

3554

@c Returns a cons cell @code{(@var{col} . @var{row})} of the viewport

3555

@c holding the top-left corner of @var{window}.

3556

@c @end defun

3557

@c

3558

@c @defun window-outside-viewport-p window

3559

@c @defunx window-outside-workspace-p window

3560

@c Returns true if @var{window} is completely outside the current

3561

@c viewport in any direction. The @code{window-outside-workspace-p}

3562

@c function is an obsolete alias for the first function; the

3563

@c ``workspace'' term is now used for another concept

3564

@c (@pxref{Workspaces}).

3565

@c @end defun

3566

@c

3567

@c @defun window-absolute-position window

3568

@c Returns a cons cell @code{(@var{x} . @var{y})} of the position of

3569

@c @var{window} in its containing viewport. The containing viewport may

3570

@c or may not be the current viewport.

3571

@c @end defun

3572

@c

3573

@c @defun set-viewport x y

3574

@c Change the position of the physical display, such that location

3575

@c @code{(@var{x}, @var{y})} is at the top-left of the display. The

3576

@c physical display may be showing more than one cell at this point.

3577

@c All windows are redisplayed as appropriate.

3578

@c @end defun

3579

@c

3580

@c @defvar uniconify-to-current-viewport

3581

@c When true, windows uniconify to the current viewport, rather than to

3582

@c the viewport they were iconified on. Defaults to true.

3583

@c @end defvar

3584

3585

@node Workspaces, Multi-Head Environments, Window Frames, Top

1888

3586

@chapter Workspaces

1889

3587

@cindex Workspaces

1890

3588

@cindex Desktop workspaces

1891

3589

1892

XXX what do I want to say here?

1893

1894

1895

@node Popup Menus, Events, Workspaces, Top

3590

Workspaces provide another way for users to organize their windows in

3591

Sawfish. Instead of stretching the screen real estate to the right

3592

and down, workplaces stack screens on top of each other. The user

3593

drills down into the stack, or pops up through the stack, seeing the

3594

appropriate windows in each workspace.

3595

3596

@menu

3597

* Workspace Intervals:: ``Interesting'' workspaces

3598

* Workspace Manipulation:: Creating, rearranging, deleting

3599

* Workspaces and Windows:: Adding, removing

3600

* Edge Flipping:: Moving workspaces using the mouse

3601

@end menu

3602

3603

@node Workspace Intervals, Workspace Manipulation, Workspaces, Workspaces

3604

@section Workspace Intervals

3605

3606

While the stack of workspaces conceptually goes from negative infinity

3607

to positive infinity, we normally present only the first non-empty

3608

workspace through the last non-empty workspace to the user. The

3609

non-empty interval is occasionally re-normalized to start with zero.

3610

3611

We typically refer to workplaces with lower IDs being to the ``left''

3612

of workplaces with higher IDs, as if on a number line.

3613

3614

@defvar current-workspace

3615

The ID of the currently active workspace. This is an integer. The

3616

``default'' workspace has ID 0.

3617

@end defvar

3618

3619

@defun workspace-limits

3620

Returns a pair @code{(@var{first-index} . @var{last-index})} defining

3621

the subset of the workspace continuum that is ``interesting'' to the

3622

user (typically, all those that have ever been explicitly created).

3623

@end defun

3624

3625

@defun workspace-id-to-logical space-id &optional limits

3626

Takes an absolute workspace ID and returns its position in the

3627

interval of ``interesting'' workspaces. If @var{limits} is provided,

3628

it must be a pair @code{(@var{first-index} . @var{last-index})} like

3629

that returned by @code{workspace-limits}. If it is not provided, the

3630

function uses the result of @code{workspace-limits} directly.

3631

@end defun

3632

3633

@defun workspace-id-from-logical offset &optional limits

3634

Takes an offset position into an interval of ``interesting''

3635

workspaces, and returns the workplace ID at that position. If

3636

@var{limits} is provided, it must be a pair @code{(@var{first-index}

3637

. @var{last-index})} like that returned by @code{workspace-limits}.

3638

If it is not provided, the function uses the result of

3639

@code{workspace-limits} directly.

3640

@end defun

3641

3642

@defun popup-workspace-list

3643

Display the menu containing the list of all workspaces.

3644

@end defun

3645

3646

@defun workspace-menu

3647

Returns a list of workspaces, suitable for display in a menu.

3648

@end defun

3649

3650

@defvr Customizable workspace-names

3651

A list of workspace names. When displaying the workspace menu, the

3652

first @var{N} workspaces use the corresponding list elements as their

3653

display names (where @var{N} is the length of the list). Normally

3654

they get the display name @samp{space N} for some value of N.

3655

@end defvr

3656

3657

@node Workspace Manipulation, Workspaces and Windows, Workspace Intervals, Workspaces

3658

@section Workspace Manipulation

3659

3660

Sawfish has various functions to create, rearrage and delete

3661

workspaces. Windows in a deleted workspace are not lost; they are

3662

moved to another workspace.

3663

3664

@defun select-workspace space &key dont-focus force

3665

Activate workspace @var{space}, making it current.

3666

3667

By default in @code{enter} and @code{click} focus modes, the most

3668

recently used window will receive focus. The caller can disable this

3669

behavior by passing a true @var{dont-focus} keyword argument.

3670

3671

If the @var{force} keyword argument is true, we will go through the

3672

activation process even if @var{space} already is current.

3673

@end defun

3674

3675

@defun select-workspace-from-first count

3676

Select the workspace in position @var{count} from the list of

3677

``interesting'' workspaces.

3678

@end defun

3679

3680

@defun select-workspace-and-viewport space col row

3681

Select workspace @var{space} and then switch to viewport

3682

@code{(@var{col}, @var{row})} in that workspace.

3683

@end defun

3684

3685

@defun insert-workspace &optional before

3686

Insert a new workspace, returning its index. The new index appears

3687

before the workspace indicated by @var{before}, or the current

3688

workspace if @var{before} is @code{nil}.

3689

@end defun

3690

3691

@defun insert-workspace-after

3692

Create a new workspace following the current workspace.

3693

@end defun

3694

3695

@defun insert-workspace-before

3696

Create a new workspace preceeding the current workspace.

3697

@end defun

3698

3699

@defun move-workspace space count

3700

Move the workspace @var{space} @var{count} positions forward, or

3701

@var{count} positions backwards if @var{count} is negative.

3702

@end defun

3703

3704

@defun move-workspace-forwards &optional count

3705

Move the current workspace one place to the right (or @var{count}

3706

places to the right if @var{count} is defined).

3707

@end defun

3708

3709

@defun move-workspace-backwards &optional count

3710

Move the current workspace one place to the left (or @var{count}

3711

places to the left if @var{count} is defined).

3712

@end defun

3713

3714

@defun next-workspace count

3715

@defunx previous-workspace count

3716

Switch from the current workspace (index @var{i}) to the workspace

3717

@var{i}+@var{count}. The @code{previous-workspace} function is

3718

identical to @code{(next-workspace (- @var{count}))}.

3719

3720

These functions do not have default values for their @var{count}

3721

arguments.

3722

@end defun

3723

3724

@defun remove-workspace &optional index

3725

Remove workspace @var{index} (or the current workspace if @var{index}

3726

is @code{nil}). All windows in that workspace are moved to the next

3727

workspace @var{index}+1. This will change the set of ``interesting''

3728

workspaces.

3729

@end defun

3730

3731

@defun merge-next-workspace

3732

Delete the current workspace. Its member windows are relocated to the

3733

next workspace.

3734

@end defun

3735

3736

@defun merge-previous-workspace

3737

Delete the current workspace. Its member windows are relocated to the

3738

previous workspace.

3739

@end defun

3740

3741

@defun set-number-of-workspaces wanted

3742

Add or remove workspaces until the number of ``interesting''

3743

workspaces is equal to @var{wanted}.

3744

3745

When adding workplaces, the new workplaces get indices higher than any

3746

existing indices. When removing workplaces, the lowest workplaces are

3747

always chosen for removal (their windows are merged into the new

3748

lowest-index workspace).

3749

@end defun

3750

3751

@defvar lock-first-workspace

3752

When true, preserve the outermost empty workspaces in the pager.

3753

Don't quietly remove them when they become empty. Defaults to true.

3754

@end defvar

3755

3756

@node Workspaces and Windows, Edge Flipping, Workspace Manipulation, Workspaces

3757

@section Workspaces and Windows

3758

3759

Workspaces do not need to have windows assigned to them, but most

3760

operations with workspaces involve adding and removing windows.

3761

3762

@defun all-workspaces

3763

Returns a list of indices for all workspaces that contain windows.

3764

Sticky windows appear in the current workspace.

3765

@end defun

3766

3767

@defun workspace-empty-p space

3768

Returns true if workspace @var{space} contains zero (non-sticky)

3769

windows.

3770

@end defun

3771

3772

@defun delete-empty-workspaces

3773

Delete any workspaces that don't contain any windows.

3774

@end defun

3775

3776

@defvar workspace-boundary-mode

3777

How to act when passing the first or last workspace, one of @code{stop},

3778

@code{wrap-around} or @code{keep-going}. Defaults to @code{stop}.

3779

@end defvar

3780

3781

Each window can be a member of any (positive) number of workspaces;

3782

their @code{workspaces} property contains a list of workspace ids.

3783

Sticky windows appear on all workspaces, and have their @code{sticky}

3784

property set (with a null @code{workspaces} property). If Sawfish

3785

begins managing a window with its @code{workspaces} property set, then

3786

the window is added to those workspaces automatically.

3787

3788

@defun window-in-workspace-p window space

3789

Returns true if @var{window} is a member of workspace @var{space},

3790

false otherwise.

3791

@end defun

3792

3793

@defun window-appears-in-workspace-p window space

3794

Returns true if @var{window} appears in workspace @var{space}, false

3795

otherwise. To appear, @var{window} has to be visible, but it can

3796

either be assigned to the workspace or be sticky.

3797

@end defun

3798

3799

@defun windows-share-workspace-p window1 window2

3800

Returns true if @var{window1} and @var{window2} are members of at

3801

least one common workspace.

3802

@end defun

3803

3804

@defun nearest-workspace-with-window window space

3805

Returns the nearest workspace to @var{space} that contains

3806

@var{window}.

3807

@end defun

3808

3809

@defun workspace-windows &optional space include-iconified

3810

Returns a list of all windows that are members of the current

3811

workspace (or @var{space} if it is not @code{nil}). The list normally

3812

does not contain iconified windows, but they can by included by

3813

specifying a true @var{include-iconified} argument.

3814

@end defun

3815

3816

@defun popup-window-menu

3817

Display the menu of all managed windows.

3818

@end defun

3819

3820

@defun move-window-to-workspace window old new &optional was-focused

3821

Move @var{window} from workspace @var{old} to workspace @var{new}.

3822

3823

We need the old workspace as an explicit argument because a window can

3824

be in more than one workspace. The function does the right thing if

3825

the window already appears in workspace @var{new}.

3826

3827

If @var{was-focused} is true and the window is visible, it gets the

3828

input focus in the new workspace.

3829

@end defun

3830

3831

@defun copy-window-to-workspace window old new &optional was-focused

3832

Arrange it so @var{window} appears in both @var{old} and @var{new}

3833

workspaces.

3834

3835

If @var{was-focused} is true and the window is visible, it gets the

3836

input focus in the new workspace.

3837

@end defun

3838

3839

@defun send-to-next-workspace window count &optional copy select

3840

Move the window @var{count} workspaces to the right. @var{Count} does

3841

not default to one.

3842

3843

The window is normally removed from the current workspace (if it is in

3844

that workspace), or from the first workspace it belongs to. Supplying

3845

a true @var{copy} argument causes Sawfish to copy the window instead.

3846

3847

If @var{select} is true, then we switch to the destination workspace.

3848

If the moved window had input focus before the move, it will have

3849

input focus after the move as well.

3850

@end defun

3851

3852

@defun send-to-previous-workspace window count &optional copy select

3853

Move the window @var{count} workspaces to the left. @var{Count} does

3854

not default to one.

3855

3856

The window is normally removed from the current workspace (if it is in

3857

that workspace), or from the first workspace it belongs to. Supplying

3858

a true @var{copy} argument causes Sawfish to copy the window instead.

3859

3860

If @var{select} is true, then we switch to the destination workspace.

3861

If the moved window had input focus before the move, it will have

3862

input focus after the move as well.

3863

3864

This is identical to @code{(send-to-next-workspace window count copy select)}.

3865

@end defun

3866

3867

@defun copy-to-next-workspace window count select

3868

Copy the window @var{count} workspaces to the left. @var{Count} does

3869

not default to one.

3870

3871

If @var{select} is true, then we switch to the destination workspace.

3872

If the moved window had input focus before the move, it will have

3873

input focus after the move as well.

3874

3875

This is identical to @code{(send-to-next-workspace window count t select)}.

3876

@end defun

3877

3878

@defun copy-to-previous-workspace window count &optional select

3879

Copy the window @var{count} workspaces to the right. @var{Count} does

3880

not default to one.

3881

3882

If @var{select} is true, then we switch to the destination workspace.

3883

If the moved window had input focus before the move, it will have

3884

input focus after the move as well.

3885

3886

This is identical to @code{(send-to-previous-workspace window count t select)}.

3887

@end defun

3888

3889

@defun send-window-to-workspace-from-first window count &optional copy select

3890

Move @var{window} to the workspace at position @var{count} in the

3891

``interesting'' list.

3892

3893

The window is normally removed from the current workspace (if it is in

3894

that workspace), or from the first workspace it belongs to. Supplying

3895

a true @var{copy} argument causes Sawfish to copy the window instead.

3896

3897

If @var{select} is true, then we switch to the destination workspace.

3898

If the moved window had input focus before the move, it will have

3899

input focus after the move as well.

3900

@end defun

3901

3902

@defvar workspace-send-boundary-mode

3903

How to act when passing the first or last workspace, while moving a

3904

window. One of @code{stop}, @code{keep-going}, @code{wrap-around}.

3905

Defaults to @code{stop}.

3906

@end defvar

3907

3908

@defun delete-window-instance window

3909

Remove the copy of @var{window} on the current workspace. If this is

3910

the last instance remaining, then delete the actual window. Note that

3911

this behavior differs from the merging that happens when you delete a

3912

workspace.

3913

@end defun

3914

3915

@defun map-window-workspaces fun window

3916

Map function @var{fun} over all workspaces containing @var{window}.

3917

@end defun

3918

3919

When a window appears on more than one workspace, some of its

3920

properties may be swapped in and out on demand when the current

3921

workspace is changed.

3922

3923

@defvar workspace-local-properties

3924

Window properties whose values may differ on differnet workspaces.

3925

Defaults to the empty list.

3926

@end defvar

3927

3928

@defvar add-swapped-properties props

3929

Add all properties in the list @var{props} to

3930

@var{workspace-local-properties}.

3931

@end defvar

3932

3933

It is possible to hide all ``normal'' windows across workspaces.

3934

``Normal'' in this case excludes desktop windows and dock windows, but

3935

includes sticky and ignored windows. The hidden windows are no longer

3936

considered ``viewable'' according to @code{window-viewable-p}.

3937

3938

@defun show-desktop

3939

Hide all windows except the desktop and dock windows.

3940

@end defun

3941

3942

@defun hide-desktop

3943

Undo the effects of the @code{show-desktop} command.

3944

@end defun

3945

3946

@defun showing-desktop-p

3947

Return true if non-desktop and non-dock windows are hidden, false

3948

otherwise.

3949

@end defun

3950

3951

@node Edge Flipping, , Workspaces and Windows, Workspaces

3952

@section Edge Flipping

3953

3954

Sawfish provides a way to flip between workspaces (or viewports)

3955

automatically by moving the mouse to the edge of the screen. The

3956

technique is called ``edge flipping''.

3957

3958

These definitions are stored in the @code{sawfish.wm.ext.edge-flip}

3959

structure. They can only be enabled through the customization

3960

interface.

3961

3962

@defvr Customizable edge-flip-enabled nil

3963

When true, select the next desktop when the pointer hits screen edge.

3964

Defaults to false.

3965

@end defvr

3966

3967

@defvr Customizable edge-flip-type

3968

Indicates what is selected when hitting the screen edge. Must be one

3969

of @code{viewport} or @code{workspace}. Defaults to @code{workspace}.

3970

@end defvr

3971

3972

@defvr Customizable edge-flip-only-when-moving

3973

When true, Sawfish only flips when the user is interactively moving a

3974

window. Defaults to false.

3975

@end defvr

3976

3977

This variable is not customizable, but it can be edited.

3978

3979

@defvar edge-flip-delay

3980

Milliseconds to delay before edge flipping. Defaults to 250.

3981

@end defvar

3982

3983

Flippers are implemented as invisible windows on the edges of the

3984

display (the windows overlap at the corners). When the pointer moves

3985

over any of these windows, Sawfish generates @code{enter-flipper-hook}

3986

and @code{leave-flipper-hook} events.

3987

3988

Programmers can add their own callbacks to perform other actions with

3989

the flippers. This depends on manually enabling the flippers, using

3990

the following functions in the @code{sawfish.wm.util.flippers}

3991

structure. Note that you may have to manually remove the

3992

@code{edge-flip-enter} and @code{edge-flip-leave} callbacks from the

3993

hooks before adding your own callbacks.

3994

3995

@defun enable-flippers

3996

Add edge windows used to implement flipping.

3997

@end defun

3998

3999

@defun disable-flippers

4000

Remove the edge windows used to implement flipping.

4001

@end defun

4002

4003

@node Multi-Head Environments, Window Placement, Workspaces, Top

4004

@chapter Multi-Head Environments

4005

@cindex Multi-head environments

4006

@cindex Environments, multi-head

4007

@cindex Monitors, multiple

4008

4009

Sawfish has special functions to support environments with multiple

4010

monitors displaying a single logical screen (as provided by Xinerama).

4011

4012

@defun find-head x y

4013

Return a ID for the display head that point (@var{x}, @var{y}) is in.

4014

The return value is an integer; the default head has ID zero. Returns

4015

@code{nil} if it cannot determine the head from @var{x} and @var{y}.

4016

@end defun

4017

4018

@defun head-count

4019

Return the number of display heads on the machine.

4020

@end defun

4021

4022

@defun head-dimensions id

4023

Return the cons cell @code{(@var{width} . @var{height})} of the

4024

dimensions of the display head indicated by @var{id}. @var{Id} must

4025

be a non-negative integer. Without Xinerama support, @var{id} must be

4026

zero and the function returns the screen size.

4027

@end defun

4028

4029

@defun head-offset id

4030

Return the cons cell @code{(@var{x} . @var{y})} of the

4031

dimensions of the display head indicated by @var{id}. @var{Id} must

4032

be a non-negative integer. Without Xinerama support, @var{id} must be

4033

zero and the function returns @code{(0 . 0)}.

4034

@end defun

4035

4036

@defun pointer-head

4037

Return the ID of the head containing the mouse pointer.

4038

@end defun

4039

4040

@defun current-head &optional window

4041

Return the ID of the head containing the window with input focus. If

4042

@var{window} is supplied and a window, return the head containing that

4043

window. If @var{window} is supplied and @var{nil}, return

4044

@code{(pointer-head)}.

4045

@end defun

4046

4047

@defun current-head-dimensions &optional window

4048

Return a cons-cell defining the size in pixels of the current head

4049

(that containing the window @var{window}, or the pointer if

4050

@var{window} is false). Returns the screen dimensions if no such head

4051

can be identified.

4052

@end defun

4053

4054

@defun current-head-offset &optional window

4055

Return a cons-cell defining the origin of the current head (that

4056

containing the window @var{window}, or the pointer if @var{window} is

4057

false). Returns @code{'(0 . 0)} if no such head can be identified.

4058

@end defun

4059

4060

4061

@node Window Placement, Popup Menus, Multi-Head Environments, Top

4062

@chapter Window Placement

4063

@cindex Placement of windows

4064

4065

Sawfish supports multiple ways of placing new windows on the display.

4066

There is a ``current'' placement mode for normal windows, and another

4067

mode for transient windows.

4068

4069

@defvar place-window-mode

4070

A symbol indicating the method of placing normal windows. This

4071

defaults to @code{top-left}.

4072

@end defvar

4073

4074

@defvar place-transient-mode

4075

A symbol indicating the method of placing transient windows. This

4076

defaults to @code{centered-on-parent}.

4077

@end defvar

4078

4079

@defun placement-mode name

4080

Return the placement mode object corresponding to @var{name}.

4081

@end defun

4082

4083

@defvar placement-modes

4084

List of names of all placement modes. Sawfish 1.3 ships with the

4085

following placement modes:

4086

4087

@itemize @bullet

4088

@item @code{randomly}

4089

The new window is placed at a random location on the screen.

4090

4091

@item @code{interactively}

4092

Prompt the user to select a position with the mouse. The new window

4093

is created such that its top-left corner is at that position.

4094

4095

@item @code{centered}

4096

The new window is created at the center of the screen.

4097

4098

@item @code{centered-on-parent}

4099

The new window has a parent, it is centered on that parent. If the

4100

new window instead has a focused window in the same group, it is

4101

centered on that focused window. Otherwise the new window is simply

4102

@code{centered}.

4103

4104

@item @code{under-pointer}

4105

Create the new window so that it's under the pointer, without going

4106

off the edge of the screen.

4107

4108

@item @code{first-fit}

4109

@item @code{best-fit}

4110

Look for positions where the new window would have a small overlap

4111

area with already visible windows. The @code{first-fit} algorithm

4112

uses the first ``good'' position found. The @code{best-fit} algorithm

4113

looks at all possible positions and picks the best of them.

4114

4115

@item @code{best-fit-group}

4116

As @code{best-fit}, but the new window is only checked for overlap

4117

with other windows in its group.

4118

4119

@item @code{first-fit-or-interactive}

4120

As @code{first-fit}, but if Sawfish cannot find a ``good'' position,

4121

it falls back to @code{interactively} mode.

4122

4123

@item @code{stagger}

4124

Attempts to place each new window below and to the right of the

4125

previous window. See @code{stagger-placement-step}.

4126

4127

@item @code{top-left}

4128

Interpret the top-left to bottom-right screen diagonal as a series of

4129

slots, each of which may have a window. Find the first empty slot and

4130

place the window there. @emph{Sawfish will shrink the window to

4131

prevent it from going past the right or bottom edge, or even beneath a

4132

special window like a panel.} If Sawfish is not allowed to shrink the

4133

window enough to prevent this, it instead places the window randomly.

4134

4135

@item @code{off-center}

4136

Tries to put windows in the center of the screen, but in such a way

4137

that the newly placed window doesn't fully obscure an existing

4138

window.

4139

4140

This is to handle the case where two windows of the same size are

4141

created one after the other, so that the user is sure to see (at least

4142

part of) both windows.

4143

@end itemize

4144

4145

@item @code{none}

4146

Make no changes to the window's position. The window remains wherever

4147

the X server placed it initially.

4148

4149

@end defvar

4150

4151

In all of these placement modes, the mode is responsible for taking

4152

the window object as an argument, and manipulating its position with,

4153

e.g., @code{move-window-to}.

4154

4155

@defvar stagger-placement-step

4156

In @code{stagger} placement mode, the distance down and to the right

4157

from the previously placed window to the new one. This is measured

4158

in pixels.

4159

@end defvar

4160

4161

There are two circumstances in which Sawfish will place a window:

4162

either the window has just been created, or Sawfish has begun managing

4163

the window's display. In the latter case, the window will have the

4164

@code{placed} property.

4165

4166

@defvar ignore-program-positions

4167

When @code{t}, program position size hints are not considered when

4168

placing windows.

4169

@end defvar

4170

4171

``Avoided'' windows should be kept unobscured by other windows

4172

wherever possible. In particular, first-fit and best-fit methods will

4173

attempt to place new windows away from them, and maximized windows

4174

will not stretch over them.

4175

4176

@defun window-avoided-p window

4177

Return t if @var{window} should be kept unobscured by other windows

4178

wherever possible.

4179

@end defun

4180

4181

@defun avoided-windows &optional window

4182

Returns a list of all windows that should be left unobscured where

4183

possible. If @var{window} is defined, then it defines a window that

4184

will be never returned in the list.

4185

@end defun

4186

4187

@defvar dont-avoid-ignored

4188

When non-nil, ignored windows aren't avoided by default. Defaults to

4189

non-nil.

4190

@end defvar

4191

4192

@defvar avoid-by-default

4193

When non-nil, any unspecified windows are avoided by default.

4194

Defaults to nil.

4195

@end defvar

4196

4197

You can define your own placement modes.

4198

4199

@defun define-placement-mode name fun &keywords for-normal for-dialogs

4200

Define a new window placement mode called @var{name} (a symbol). The

4201

function @var{fun} will be called with a single argument when a window

4202

should be placed using this mode. The single argument is the window

4203

to be placed.

4204

4205

If the @var{for-normal} keyword is @code{t}, then this placement mode

4206

is marked as valid for @code{place-window-mode}. The same applies to

4207

@var{for-dialogs} and @code{place-transient-mode}.

4208

@end defun

4209

4210

@defun autoload-placement-mode name module-name &keywords for-normal for-dialogs

4211

Define placement mode @var{name} (a symbol) to be loaded from

4212

structure @var{structure-name} (a symbol) when first referenced. The

4213

@var{keyword-args} are passed along to the call to

4214

@code{define-placement-mode} that creates the placement mode.

4215

@end defun

4216

4217

@node Popup Menus, Events, Window Placement, Top

1896

4218

@chapter Popup Menus

1897

4219

@cindex Popup menus

1898

4220

@cindex Menus, popup

1964

4286

The @code{system} function simply executes its single argument using

1965

4287

@file{/bin/sh}.

1966

4288

4289

When displaying a menu item, it is possible to also display the

4290

corresponding keyboard shortcut in the menu.

4291

4292

@defvar menus-include-shortcuts

4293

When true, menu items also display key-binding information. Defaults

4294

to false.

4295

@end defvar

4296

4297

The actual creation of a menu is performed by an auxiliary process,

4298

distributed with Sawfish. Since the overhead of starting the menu

4299

subprocess may be noticeable on some systems, it is possible to leave

4300

it running between menu requests.

4301

4302

@defvar menu-program

4303

Location of the program implementing Sawfish's menu interface.

4304

@end defvar

4305

4306

@defvar menu-program-stays-running

4307

This variable defines if, and for how long, the menu subprocess is

4308

allowed to remain executing for after the last menu has completed. If

4309

@code{nil}, the program is terminated immediately, if @code{t} it is

4310

left running indefinitely, if an integer then the program will run for

4311

that many seconds (unless another menu is displayed).

4312

@end defvar

4313

4314

The actual interface to invoke the external menu program is hidden in

4315

the @code{popup-menu} function.

4316

1967

4317

@defun popup-menu spec

1968

4318

Displays a menu defined by the list of item definitions @var{spec}.

1969

4319

@end defun

1970

4320

1971

@defun popup-window-menu

1972

Display the menu listing all window operations.

1973

@end defun

1974

1975

@defun popup-root-menu

1976

Display the main menu.

1977

@end defun

1978

1979

@defun popup-apps-menu

1980

Displau the applications menu.

1981

@end defun

4321

In addition, Sawfish provides various canned menus, and functions to

4322

display those menus.

1982

4323

1983

4324

@defvar root-menu

1984

4325

Contains the root menu definition.

1985

4326

@end defvar

1986

4327

4328

@defun popup-root-menu

4329

Display the main menu. By default, this is bound to Button2-click on

4330

the root window.

4331

@end defun

4332

1987

4333

@defvar apps-menu

1988

4334

The variable containing the definition of the applications submenu of

1989

the root menu.

1990

@end defvar

1991

1992

Since the overhead of starting the menu subprocess may be noticeable on

1993

some systems, it is possible to leave it running between menu requests.

1994

1995

@defvar menu-program-stays-running

1996

This variable defines if, and for how long, the menu subprocess is

1997

allowed to remain executing for after the last menu has completed. If

1998

@code{nil}, the program is terminated immediately, if @code{t} it is

1999

left running indefinitely, if an integer then the program will run for

2000

that many seconds (unless another menu is displayed).

2001

@end defvar

2002

4335

the root menu. The default root menu includes this as a child menu.

4336

@end defvar

4337

4338

@defun popup-apps-menu

4339

Display the applications menu.

4340

@end defun

4341

4342

@defun window-ops-menu

4343

The variable containing the definition of all window operations.

4344

@end defun

4345

4346

@defun popup-window-menu

4347

Display the menu listing all window operations. This has several

4348

bindings by default. In particular, clicking on a window's menu

4349

button displays this menu.

4350

@end defun

4351

4352

@defvar window-ops-toggle-menu

4353

A list of flags describing windows, e.g., ``sticky'' or ``shaded''.

4354

This list is displayed in a menu, and by selecting items in this menu

4355

a user can turn the flags on and off for a given window.

4356

@end defvar

4357

4358

@defun add-window-menu-toggle label command &optional predicate

4359

Add additional flags to @code{window-ops-toggle-menu}. The

4360

@var{command} is a function (or a symbol pointing to a function) that

4361

gets run when the menu item is selected. If @var{predicate} is

4362

non-nil, it must be a function taking a window as argument. If

4363

@var{predicate} return true, the menu item will have a check mark next

4364

to it.

4365

@end defun

2003

4366

2004

4367

@node Events, Commands, Popup Menus, Top

2005

4368

@chapter Events

2010

4373

from the client windows themselves. Each event induced by the mouse or

2011

4374

keyboard has a Lisp representation.

2012

4375

2013

Each input event is represented by a cons cell containing two integers,

2014

these integers encode the actual input event. The encoding is opaque;

4376

@defun eventp object

4377

This function returns @code{t} if its argument is an input event.

4378

@end defun

4379

4380

@menu

4381

* Event Representation:: Objects versus string names

4382

* Event Modifiers:: Meta, Alt, Buttons

4383

* Event Actions:: Keys and Clicks

4384

* Event Matching::

4385

* Synthetic Events:: Creating events that seem real

4386

@end menu

4387

4388

@node Event Representation, Event Modifiers, Events, Events

4389

@section Event Representation

4390

4391

Each input event is represented by a cons cell containing two

4392

integers, and these integers encode the event. The encoding is opaque;

2015

4393

the only way to access an event meaningfully is via the functions

2016

4394

provided.

2017

4395

2018

@defun eventp object

2019

This function returns @code{t} if its argument is an input event.

2020

@end defun

2021

2022

Each event has a name, a string. This string contains zero or more

2023

modifier descriptions separated by hyphens, and then the name of the

2024

key itself. The standard X modifier names are provided, as well as

2025

three special modifiers @key{Meta}, @key{Alt} and @key{Hyper} that are

2026

mapped to the keysyms of the same name.

2027

2028

The following table lists the possible modifier prefixes:

2029

2030

@table @kbd

2031

@item C

2032

The control modifier

2033

2034

@item M

2035

The meta modifier

2036

2037

@item A

2038

The alt modifier

2039

2040

@item S

2041

The shift modifier

2042

2043

@item H

2044

The hyper modifier

2045

2046

@item Mod@var{k}

2047

The standard X modifiers, for @var{k} between 1 and 5

2048

2049

@item Button@var{k}

2050

The @var{k}'th mouse button is currently pressed

2051

@end table

2052

2053

Note that the @samp{M} and @samp{A} modifiers are virtual modifiers

2054

assigned dynamically, according to the X server's @code{xmodmap}

2055

configuration. The @samp{A} virtual modifier is assigned to the X

2056

modifier with either the @key{Alt_L} or @key{Alt_R} keysym assigned to

2057

it. The @samp{M} virtual modifier is assigned to the X modifier with

2058

either @key{Meta_L} or @key{Meta_R} assigned to it. If either of these

2059

two virtual modifiers would be unassigned it is set identically to the

2060

other virtual modifier.

2061

2062

There are two special modifiers: the @samp{Any} prefix matches any set

2063

of modifiers; the @samp{Release} modifier matches key-release events

2064

instead of the default key-presses.

2065

2066

Generally keys have the same names as their X keysyms, there are

2067

several specially defined keys:

2068

2069

@samp{SPC}, @samp{TAB}, @samp{RET}, @samp{ESC}, @samp{BS}, @samp{DEL},

2070

@samp{Up}, @samp{Down}, @samp{Left}, @samp{Right}.

2071

2072

@noindent

2073

Also, there are several pseudo-keys for describing mouse events:

2074

2075

@samp{Click1}, @samp{Click2}, @samp{Click3}, @samp{Off}, @samp{Move}.

2076

2077

@noindent

2078

So, for example, a single click of the left mouse button with the

2079

@key{Meta} key held would be described as @kbd{M-Button1-Click1}, while

2080

pressing the @key{RET} key with @key{Shift} held would be described as

2081

@kbd{S-RET}.

4396

Each event has a string representation, called its ``name''. Names

4397

consist of zero or more modifiers, followed by a key or mouse action

4398

indicator. Modifiers are separated from succeeding elements by

4399

hyphens @samp{-}. For example, hitting @key{x} while holding down the

4400

@key{Control} and @key{Meta} keys would generate an event named

4401

@key{Control-Meta-x}. This notation is designed to closely match

4402

Emacs Lisp's notation.

2082

4403

2083

4404

Functions are available to convert between the name of an event and the

2084

4405

actual event itself, and vice versa.

2104

4425

@end lisp

2105

4426

@end defun

2106

4427

2107

The keysyms generating the two virtual modifiers may be identified

2108

through the following variables:

4428

@node Event Modifiers, Event Actions, Event Representation, Events

4429

@section Event Modifiers

4430

@cindex Event Modifiers

4431

@cindex Modifiers, for events

4432

4433

Sawfish event modifiers are copied directly from the standard X

4434

modifiers:

4435

4436

The standard X modifier names are provided, as well as four special

4437

modifiers @key{Meta}, @key{Alt} @key{Hyper} and @key{Super} that are

4438

mapped to the keysyms of the same name.

4439

4440

The following table lists the possible modifier prefixes:

4441

4442

@table @key

4443

@item Control

4444

@itemx C

4445

The control modifier

4446

4447

@item Meta

4448

@itemx M

4449

The meta modifier

4450

4451

@item Alt

4452

@itemx A

4453

The alt modifier

4454

4455

@item Shift

4456

@itemx S

4457

The shift modifier

4458

4459

@item Hyper

4460

@itemx H

4461

The hyper modifier

4462

4463

@item Super

4464

@itemx s

4465

The super modifier; note that this is a lowercase @kbd{s}

4466

4467

@item Mod@var{k}

4468

The standard X modifiers, for @var{k} between 1 and 5

4469

4470

@item Any

4471

A special modifier that matches any set of modifiers in events.

4472

@xref{Event Matching}.

4473

4474

@item Release

4475

A special modifier that matches key release events, not the default

4476

key press events. Mouse events never have @key{Release} modifiers;

4477

they have separate actions instead. @xref{Event Actions}.

4478

4479

@item Button@var{k}

4480

The @var{k}'th mouse button is currently pressed.

4481

4482

@item W

4483

A placeholder ``window manager'' modifier that can be bound to a real

4484

modifier on the fly. See @code{wm-modifier} below.

4485

@end table

4486

4487

The default Sawfish bindings use the @key{Meta} modifier. For

4488

convenience, if no X keysym generates @key{Meta}, Sawfish will treat

4489

the first defined modifier of @key{Alt}, @key{Hyper} and @key{Super}

4490

(in that order) as @key{Meta}. The mapping from keysyms to

4491

modifiers is exposed in the following variables:

2109

4492

2110

4493

@defvar meta-keysyms

2111

4494

A list defining the names of the X keysyms generating the virtual

2112

@samp{M} modifier.

4495

@samp{Meta} or @samp{M} modifier.

2113

4496

@end defvar

2114

4497

2115

4498

@defvar alt-keysyms

2116

4499

A list defining the names of the X keysyms generating the virtual

2117

@samp{A} modifier.

4500

@samp{Alt} or @samp{A} modifier.

2118

4501

@end defvar

2119

4502

2120

4503

@defvar hyper-keysyms

2121

4504

A list defining the names of the X keysyms generating the virtual

2122

@samp{H} modifier.

2123

@end defvar

4505

@samp{Hyper} or @samp{H} modifier.

4506

@end defvar

4507

4508

@defvar super-keysyms

4509

A list defining the names of the X keysyms generating the virtual

4510

@samp{Super} modifier.

4511

@end defvar

4512

4513

There are two functions to manipulate the placeholder ``window

4514

manager'' (@key{W}) modifier. Unfortunately, these are low-level

4515

functions that operate on integer encodings.

4516

4517

@defun wm-modifier

4518

Return the current value (an integer) of the placeholder ``window

4519

manager'' (@key{W}) modifier.

4520

@end defun

4521

4522

@defvr {Customizable} wm-modifier-value

4523

An integer encoding zero or more modifier keys that form the

4524

placeholder ``window manager'' (@key{W}) modifier. Setting this value

4525

through the customization UI automatically calls

4526

@code{set-wm-modifier}.

4527

@end defvr

4528

4529

@defun set-wm-modifier modifiers

4530

Set the value of the placeholder ``window manager'' (@key{W}) modifier

4531

to @var{modifiers} (an integer).

4532

@end defun

4533

4534

@node Event Actions, Event Matching, Event Modifiers, Events

4535

@section Event Actions

4536

4537

Sawfish recognizes keyboard actions and mouse actions.

4538

4539

@table @asis

4540

@item Key Press

4541

@itemx Key Release

4542

Keys pressed on the keyboard generate one or more key press events,

4543

followed by a key release event. Bindings normally recognize key

4544

press events only. To recognize key releases, add a @key{Release}

4545

modifier to the bound event.

4546

@end table

4547

4548

Generally keys have the same names as their X keysyms. The following

4549

unusual names are worth listing: @samp{SPC}, @samp{TAB}, @samp{RET},

4550

@samp{ESC}, @samp{BS}, @samp{DEL}, @samp{Up}, @samp{Down},

4551

@samp{Left}, @samp{Right}.

4552

4553

For example, pressing the @key{Delete} key while @key{Control} is held

4554

down generates a @kbd{Control-DEL} event, while releasing the @key{a}

4555

key while @key{Hyper} is held down generates a @kbd{H-Release-a}

4556

event.

4557

4558

@table @asis

4559

@item Button Clicks

4560

Button presses generate @key{Click} actions. If Sawfish receives

4561

several clicks in close succession (less than @code{multi-click-delay}

4562

milliseconds between clicks), the second and third events are

4563

@key{Click2} and @key{Click3}, respectively. Any further clicks are

4564

simple @key{Click} events. For consistency, @key{Click1} is a synonym

4565

for @key{Click}.

4566

4567

@item Button Releases

4568

Once the button has been released from a @key{ClickN} action, Sawfish

4569

receives a corresponding @key{OffN} action. The actions @key{Off} and

4570

@key{Off1} are synonyms.

4571

4572

@item Pointer Motion

4573

Pointer motion generates @key{Move} actions. The action does not

4574

indicate anything about the pointer position; use e.g.,

4575

@code{query-last-pointer} to find that information.

4576

@end table

4577

4578

@noindent

4579

For example, a single click of the left mouse button with the

4580

@key{Meta} key held would be described as @kbd{M-Button1-Click1}.

4581

After triple-clicking with the @key{Alt} key held down, Sawfish will

4582

receive a @kbd{Alt-Off3} event.

4583

4584

4585

@defvar multi-click-delay

4586

An integer indicating the maximum number of milliseconds between

4587

successive clicks. Defaults to 250 milliseconds at startup; if

4588

@code{nil}, Sawfish uses 250 milliseconds.

4589

@end defvar

4590

4591

4592

@node Event Matching, Synthetic Events, Event Actions, Events

4593

@section Event Matching

4594

@cindex Event Matching

4595

@cindex Matching, Events

4596

4597

There is a special function that matches event objects. If the

4598

actions of two event objects are not identical, the events do not

4599

match. If they are identical, then the events match if the modifiers

4600

are identical, or if one of the modifiers is @key{Any}.

4601

@xref{Event Modifiers}.

4602

4603

@defun event-match ev1 ev2

4604

Returns @code{t} if events @var{ev1} and @var{ev2} match, @code{nil}

4605

otherwise.

4606

@end defun

4607

4608

@node Synthetic Events, , Event Matching, Events

4609

@section Synthetic Events

4610

@cindex Synthetic Events

4611

@cindex Events, Synthetic

4612

@cindex Events, Synthesizing

4613

4614

It is possible to create an event inside Sawfish that mimics a real

4615

keyboard or mouse event.

4616

4617

@defun synthesize-event event window &optional propagate

4618

Generate a synthetic key press or button press and send it to the X

4619

window bound to the @var{window} object. This press is automatically

4620

followed by the appropriate release event.

4621

4622

The current pointer position becomes the position of the event.

4623

4624

@var{Event} is either an event object, or the string representation of

4625

an event (such as @code{"A-f"} or @code{"C-M-Button3-Click2"}).

4626

Strings are parsed into event objects before any work is done.

4627

@xref{Event Representation}.

4628

4629

If @var{propagate} is true, the event will propagate up the window

4630

ancestor chain until it is handled.

4631

@end defun

2124

4632

2125

4633

2126

4634

@node Commands, Keymaps, Events, Top

2128

4636

@cindex Commands

2129

4637

2130

4638

A @dfn{command} is a Lisp function which may be called interactively,

2131

that is, either as a result of being bound to an input event.

2132

2133

Commands are defined in the same way as functions (using @code{defun}),

2134

but the body forms of the command must contain an @dfn{interactive

2135

declaration}. This marks that the function may be called interactively

2136

and tells the @code{call-command} function how to compute the argument

2137

values to apply to the command.

4639

that is, as a result of being bound to an input event. To support

4640

this, we mark them with metadata that the runtime system can query.

4641

4642

@menu

4643

* Old-style Command Definition:: Emacs-Lisp style

4644

* New-style Command Definition:: Common-Lisp style

4645

* Interactive Calling Specification::

4646

* Operations on Commands:: Accessors and the like

4647

* Invoking Commands:: call-commmand, command hooks

4648

* Default Commands:: Sawfish ships with a few commands

4649

@end menu

4650

4651

@node Old-style Command Definition, New-style Command Definition, Commands, Commands

4652

@section Old-style Command Definition

4653

4654

The old-style command declaration syntax looks very much like that of

4655

GNU Emacs Lisp. Commands are defined like any other function (using

4656

@code{defun}), but the first form in the body must be an

4657

@dfn{interactive declaration}. This marks that the function may be

4658

called interactively and tells the @code{call-command} function how to

4659

compute the argument values to apply to the command.

2138

4660

2139

4661

The interactive declaration looks like a call to the special form

2140

4662

@code{interactive}, in actual fact this special form always returns

2161

4683

@dots{}

2162

4684

@end lisp

2163

4685

2164

The @var{calling-spec} form defines the argument values applied to the

2165

command when it is called interactively, it may be one of,

4686

The @var{calling-spec} is defined in @xref{Interactive Calling

4687

Specification}.

4688

4689

@node New-style Command Definition, Interactive Calling Specification, Old-style Command Definition, Commands

4690

@section New-style Command Definition

4691

4692

The new syntax does not depend on special magic in @code{defun}.

4693

Instead, it uses keyword arguments to indicate the calling

4694

specification and other properties.

4695

4696

@defun define-command name fun #!key spec type doc doc-key class

4697

Define a window managed command called @var{name} (a symbol). The

4698

function @var{fun} will be called to execute the command.

4699

4700

@var{spec} and @var{type} may be used to define the arguments expected

4701

by the command; @var{spec} is an interactive specification and

4702

@var{type} is a custom-type specification. @xref{Interactive Calling

4703

Specification}.

4704

4705

@var{doc} is the documentation string associated with the command.

4706

The command-documentation may be stored in the doc file, rather than

4707

in the code itself; if it exists, the @var{doc-key} will be used to

4708

look up the doc file entry. If both arguments are provided, both will

4709

be stored. But the @code{command-documentation} function favors the

4710

built-in doc string over the doc file entry.

4711

4712

@var{class} is an annotation for the command. It allows the

4713

definition to mark the class as @code{'advanced}, for example. Other

4714

parts of Sawfish can then take advantage of this note.

4715

@end defun

4716

4717

@defun define-command-to-screen name fun #!key spec type doc doc-key class

4718

As @code{define-command}, but any printed output of @var{fun} is sent

4719

to the screen.

4720

@end defun

4721

4722

@defun autoload-command name module #!key spec type doc doc-key class

4723

Record that loading the module called @var{module} (a symbol) will provde a

4724

command called @var{name}.

4725

4726

The keyword values have the same meanings as for

4727

@code{define-command}. Defining those properties as part of the

4728

autoload provides useful feedback to the user without having to do

4729

loading.

4730

@end defun

4731

4732

@node Interactive Calling Specification, Operations on Commands, New-style Command Definition, Commands

4733

@section Interactive Calling Specification

4734

4735

The @var{calling-spec} argument to @code{interactive} or

4736

@code{define-command} defines the argument values applied to the

4737

command when it is called interactively. It may be one of:

2166

4738

2167

4739

@itemize @bullet

2168

@item

2169

@code{nil} or undefined (i.e. @code{(interactive)}); no arguments are

2170

given to the command, this type of interactive declaration just shows

2171

that the function may be called interactively.

4740

@item @code{nil} or undefined (i.e. @code{(interactive)})

4741

No arguments are given to the command, this type of interactive

4742

declaration just shows that the function may be called interactively.

2172

4743

2173

@item A string; zero or more lines (each separated by a newline

2174

character), each line defines how to compute one argument value. The

4744

@item A string

4745

This is interpreted as zero or more lines (each separated by a newline

4746

character). Each line defines how to compute one argument value. The

2175

4747

first one or two characters of each line is a prefix defining exactly

2176

4748

how to compute the argument, the rest of the line is an optional

2177

argument which some prefixes may use.

4749

argument which some prefixes may use. See below for a list of

4750

prefixes. A null line produces an argument value of @code{nil}.

4751

4752

@item Anything else

4753

The form is evaluated and expected to return a @emph{list} of

4754

arguments to apply to the command.

4755

@end itemize

2178

4756

2179

4757

The currently available prefixes are,

2180

4758

2207

4785

this returns @code{nil} or @code{root}, the currently focused window.

2208

4786

@end table

2209

4787

2210

A null line produces an argument value of @code{nil}.

2211

2212

@item

2213

Anything else; the form is evaluated and expected to return a @emph{list}

2214

of arguments to apply to the command.

2215

@end itemize

2216

2217

When a command is to be invoked, the @code{call-command} function is

2218

used. This builds a list of argument values to apply to the command

2219

(using its interactive declaration) then calls the command.

4788

@node Operations on Commands, Invoking Commands, Interactive Calling Specification, Commands

4789

@section Operations on Commands

4790

4791

Once a command has been defined, we can extract certain information

4792

about it.

2220

4793

2221

4794

@defun commandp @var{object}

2222

4795

This function returns @code{t} if its argument may be called interactively.

2228

4801

sometimes.

2229

4802

@end defun

2230

4803

4804

@defun command-documentation name

4805

Return the documentation for the command @var{name}. It returns the

4806

first documentation found by looking at (in order): the documentation

4807

property of the command; the doc file entry associated with the doc

4808

key property; or the documentation for the function with the same

4809

name.

4810

@end defun

4811

4812

@defun command-spec name

4813

@defunx command-type name

4814

@defunx command-class name

4815

Return the specification, type or class (respectively) of the named

4816

command.

4817

@end defun

4818

4819

@node Invoking Commands, Default Commands, Operations on Commands, Commands

4820

@section Invoking Commands

4821

4822

When a command is to be invoked, the @code{call-command} function is

4823

used. This builds a list of argument values to apply to the command

4824

(using its interactive declaration) then calls the command.

4825

2231

4826

@defun call-command command &optional prefix-arg

2232

4827

This function calls the command @var{command} interactively. See the

2233

4828

documentation of @code{commandp} above for what constitutes a command.

2236

4831

@code{current-prefix-arg} variable for this command, normally the value

2237

4832

of this variable would be taken from the global @code{prefix-arg}

2238

4833

variable.

2239

@end defun

2240

4834

4835

There is a corresponding @code{call-command} command that prompts for

4836

a command to execute.

4837

@end defun

4838

4839

@defun apply-command name &rest args

4840

Call the function underlying the command @var{name}, passing in

4841

@var{args} as the arguments. This is useful for calling a command in

4842

a non-interactive context.

4843

@end defun

4844

4845

@defvar current-prefix-arg

4846

When invoking an interactive command, this is set to the current

4847

prefix argument.

4848

@end defvar

4849

4850

@defvar this-command

4851

The command currently being called, or @samp{nil} if no command is

4852

being called.

4853

@end defvar

4854

4855

@defvar last-command

4856

The command previously called, or @samp{nil} if there is no such

4857

command.

4858

@end defvar

4859

4860

@xref{Command Hooks}, for hooks run before and after commands.

4861

4862

@node Default Commands, , Invoking Commands, Commands

4863

@section Default Commands

4864

4865

Sawfish defines several commands by default.

4866

4867

@defun run-shell-command

4868

The command prompts the user for a string, and executes that string as

4869

under @code{system}.

4870

@end defun

4871

4872

@defun quit

4873

@defunx restart

4874

@defunx destroy-window

4875

@defunx kill-client

4876

@defunx no-operation

4877

Calls the function of the same name. @code{destroy-window} and

4878

@code{kill-client} both take @code{%W} as argument.

4879

@end defun

2241

4880

2242

4881

@node Keymaps, Event Loop, Commands, Top

2243

4882

@chapter Keymaps

2307

4946

@itemx iconify-button-keymap

2308

4947

@itemx maximize-button-keymap

2309

4948

@itemx menu-button-keymap

4949

@itemx shade-button-keymap

2310

4950

Keymaps active in the standard window frame buttons.

4951

4952

@item override-keymap

4953

Must be a keymap, a symbol, or @code{nil}. If it is a keymap,

4954

this becomes the keymap in which all lookups occur (overriding the window,

4955

root and global keymaps). If it is a symbol, Sawfish finds the

4956

symbol's value and tries again. If it is @code{nil}, Sawfish behaves

4957

normally.

4958

2311

4959

@end table

2312

4960

2313

4961

2377

5025

Returns the string which the current event would usually insert.

2378

5026

@end defun

2379

5027

2380

@defun current-event-window

2381

Return the window that received the current event, or the symbol

2382

@code{root}, or @code{nil} if no such window.

5028

@defun current-event-window &optional win

5029

Extract the owning window of the current X event (this is a window

5030

object, or the symbol @code{root} for the root window, or @code{nil}

5031

if there is no window or no event). This is stored internally as the

5032

current event window, and returned.

5033

@c FIXME-DLU: why does this function take a WIN parameter?

2383

5034

@end defun

2384

5035

2385

5036

@defun last-event

2391

5042

numeric window id, or the symbol @code{root}. If a @code{ButtonPress}

2392

5043

event the pointer grab will be released first.

2393

5044

2394

@var{mask} may be an integer defining the X event mask to pass to the

5045

@var{Mask} may be an integer defining the X event mask to pass to the

2395

5046

@code{XSendEvent} function. If not defined, a mask is chosen that would

2396

5047

usually be used to select the type of event being proxied.

5048

5049

@var{Propagate} is a flag (@code{nil}/non-@code{nil}) passed directly

5050

to an underlying @code{XSendEvent} call. (And if someone would like

5051

to explain what @emph{that} means, please do so @enddots{}

2397

5052

@end defun

2398

5053

2399

5054

@defun allow-events mode

2450

5105

Returns a cons cell @code{(@var{x} . @var{y})} representing the current

2451

5106

mouse pointer position, relative to the origin of the root window.

2452

5107

2453

If @var{from-server} is non-nil then the position is read directly from

2454

the server, otherwise it's taken from the current event (if possible).

5108

If there is a mouse update current event, the position is read

5109

directly from that event. Otherwise it is read from the server. If

5110

@var{from-server} is non-nil then the position is read directly from

5111

the server in any case.

2455

5112

@end defun

2456

5113

2457

5114

@defun query-pointer-window

2464

5121

most recent mouse pointer position, relative to the root window.

2465

5122

@end defun

2466

5123

5124

@defun query-button-press-pointer

5125

Returns @code{(@var{mouse-x} . @var{mouse-y})} representing the mouse

5126

position relative to the root window at the last button-press event.

5127

5128

Use this function to track the displacement of the pointer during a

5129

drag.

5130

@end defun

5131

5132

@defun query-button-press-window

5133

Returns the window that the mouse was in when the button was pressed.

5134

@end defun

5135

2467

5136

@defun warp-cursor x y

2468

5137

Move the mouse pointer to position (@var{x}, @var{y}) relative to the

2469

5138

origin of the root window.

2477

5146

top-left corner of the window's frame.

2478

5147

@end defun

2479

5148

5149

@defvar warp-to-window-offset

5150

Offset (%) from window edges when warping pointer. A negative number

5151

means outside the left window edge.

5152

@end defvar

5153

5154

@defvar warp-to-window-enabled

5155

When false, disable warping the cursor to windows.

5156

@end defvar

5157

5158

@defvar pointer-motion-threshold

5159

If set to an integer value, a pointer must move by this many pixels on

5160

either axis before Sawfish considers it to have moved. If the pointer

5161

has not moved by this amount, Sawfish will ignore @code{MotionNotify}

5162

events from X. The variable defaults to 2 pixels. If not an integer,

5163

Sawfish assumes a threshold of 0 pixels.

5164

@end defvar

5165

2480

5166

2481

5167

@node Grab Functions, Display Functions, Pointer Functions, Miscellaneous Functions

2482

5168

@section Grab Functions

2499

5185

Evaluate forms with the server grabbed. Releases the grab afterwards.

2500

5186

@end defmac

2501

5187

5188

@defun call-with-server-ungrabbed thunk

5189

Return the result of calling the zero-parameter function

5190

@var{thunk}. If the server is currently grabbed, ungrab it first,

5191

restoring the original grab status after the call to @var{thunk}

5192

returns.

5193

@end defun

5194

2502

5195

@defun server-grabbed-p

2503

5196

Returns @code{t} if the X server is currently grabbed.

2504

5197

@end defun

2505

5198

2506

@defun grab-pointer &optional window cursor

5199

@defun grab-pointer &optional window cursor ptr-sync kbd-sync confine-to

2507

5200

Grab the mouse pointer and direct all pointer events to window object

2508

@var{window}. If @var{cursor} is defined and a cursor object, display

5201

@var{window}. If @var{cursor} is defined and a cursor object, display

2509

5202

this while the pointer is grabbed.

2510

5203

2511

If @var{window} is @code{nil}, or unviewable, the grab will be made on

2512

the root window.

2513

2514

Returns @code{y} if the grab succeeded.

5204

If @var{window} is a window object corresponding to a

5205

visible window, the grab will be made on its frame.

5206

5207

If @var{window} is an integer, it specifies the window ID of the grab

5208

window.

5209

5210

Otherwise the grab will be made on the root window. This includes

5211

@var{window} corresponding to a non-viewable window.

5212

5213

@var{Confine-to}, if non-@code{nil}, is a visible window to confine

5214

the pointer to. It is interpreted similarly to the rules for

5215

@var{window}, except that the ``otherwise'' case is to not confine the

5216

pointer.

5217

5218

If the window id of a non-viewable window was specified for either

5219

@var{window} of @var{confine-to}, the grab will be made on the root

5220

window without confining the pointer.

5221

5222

If @var{ptr-sync} or @var{kbd-sync} is non-@var{nil}, the pointer or

5223

keyboard will be frozen, i.e., the device will not produce events

5224

until either the grab is released or events are re-enabled using

5225

@code{allow-events}.

5226

5227

Returns non-nil if the grab succeeded.

2515

5228

@end defun

2516

5229

2517

5230

@defun ungrab-pointer

2518

5231

Release the grab on the mouse pointer.

2519

5232

@end defun

2520

5233

2521

@defun grab-keyboard &optional window

5234

@defun grab-keyboard &optional window ptr-sync kbd-sync

2522

5235

Grab the keyboard and direct all keyboard events to window object

2523

@var{window}. If @var{window} is @code{nil}, or unviewable, the grab

2524

will be made on the root window.

5236

@var{window}.

5237

5238

If @var{window} is a window object corresponding to a

5239

visible window, the grab will be made on its frame.

5240

5241

If @var{window} is an integer, it specifies the window ID of the grab

5242

window.

5243

5244

Otherwise the grab will be made on the root window. This includes

5245

@var{window} corresponding to a non-viewable window.

5246

5247

If @var{ptr-sync} or @var{kbd-sync} is non-@var{nil}, the pointer or

5248

keyboard will be frozen, i.e., the device will not produce events

5249

until either the grab is released or events are re-enabled using

5250

@code{allow-events}.

2525

5251

2526

5252

Returns non-nil if the grab succeeded.

2527

5253

@end defun

2530

5256

Release the grab on the keyboard.

2531

5257

@end defun

2532

5258

5259

@defun call-with-keyboard-grabbed thunk

5260

Call the zero-parameter function @var{thunk} with the keyboard

5261

grabbed. If unable to grab the keyboard then @var{thunk} won't be

5262

called.

5263

@end defun

5264

2533

5265

2534

5266

@node Display Functions, Gradient Functions, Grab Functions, Miscellaneous Functions

2535

5267

@section Display Functions

2544

5276

Return the height of the root window.

2545

5277

@end defun

2546

5278

5279

@defun screen-dimensions

5280

Return the screen dimensions in pixels as a cons cell

5281

@code{(@var{width} . @var{height})}.

5282

@end defun

5283

2547

5284

@defun draw-window-outline mode x y width height

2548

5285

Draw an outline of a window of dimensions (@var{width}, @var{height})

2549

5286

at position (@var{x}, @var{y}) relative to the root window.

2626

5363

2627

5364

@defun draw-horizontal-gradient image from to

2628

5365

Draw a horizontal color gradient in @var{image}, from left to right.

5366

The color at the left of the image will be @var{from}, the color at

5367

the right @var{to}, with a smooth transition between.

2629

5368

@end defun

2630

5369

2631

5370

@defun draw-diagonal-gradient image from to

2632

5371

Draw a horizontal color gradient in @var{image}, from the top-left

2633

corner to the bottom-right.

5372

corner to the bottom-right. The color at the top-left of the image

5373

will be @var{from}, the color at the bottom-right @var{to}, with a

5374

smooth transition between.

2634

5375

@end defun

2635

5376

2636

5377

2660

5401

Returns the window id of the new window.

2661

5402

@end defun

2662

5403

5404

@defun exit-type

5405

If Sawfish is shutting down, this function returns one of the strings

5406

@code{"user-quit"}, @code{"user-restart"} or @code{"session-quit"}.

5407

If Sawfish is not shutting down, it returns @code{nil}.

5408

@end defun

5409

2663

5410

@defun x-atom symbol

2664

5411

Return the integer identifying the X atom with the same name as

2665

5412

@var{symbol}.

2670

5417

integer @var{integer}.

2671

5418

@end defun

2672

5419

5420

@defvar canonical-display-name

5421

A string containing the canonical name of the X display. This

5422

includes the full host name and the screen number. For example:

5423

@code{"foo.bar.com:0.0"}.

5424

@end defvar

5425

5426

@defvar display-name

5427

A string containing the name of the X display, exactly as passed to

5428

Sawfish. For example: @code{":0"}, or @code{"foo:0.0"}.

5429

@end defvar

5430

5431

@defvar saved-command-line-args

5432

Holds a list of all of the command line arguments (including the

5433

executable name).

5434

@end defvar

5435

5436

@defvar sawfish-directory

5437

The home directory for Sawfish files. For example:

5438

@code{"/usr/share/sawfish"}.

5439

@end defvar

5440

5441

@defvar sawfish-exec-directory

5442

The directory for architechture-specific Sawfish executables. For

5443

example: @code{"/usr/lib/sawfish/1.3/i386-pc-linux-gnu"}.

5444

@end defvar

5445

5446

@defvar sawfish-lisp-lib-directory

5447

The top-level directory for Sawfish lisp files. For example:

5448

@code{"/usr/share/sawfish/1.3/lisp"}.

5449

@end defvar

5450

5451

@defvar sawfish-locale-directory

5452

The system directory where Sawfish can find locale files. This is not

5453

part of the Sawfish distribution. For example:

5454

@code{"/usr/share/locale"}.

5455

@end defvar

5456

5457

@defvar sawfish-site-lisp-directory

5458

The top-level directory for site-specific Sawfish lisp files. For

5459

example: @code{"/usr/share/sawfish/site-lisp"}.

5460

@end defvar

5461

5462

@defvar sawfish-version

5463

The version number of the running Sawfish.

5464

@end defvar

5465

5466

@defun primitive-play-sample filename

5467

Plays the sound file @var{filename} (which must be a string).

5468

@end defun

5469

5470

@defun call-with-error-handler thunk

5471

Call the zero-parameter function @var{thunk}. If an error occurs,

5472

trap it and pass its @code{car} and @code{cdr} to

5473

@code{error-handler-function}.

5474

@end defun

5475

5476

@defun load-module name

5477

Ensure that module @var{name} has been loaded. This does @emph{not}

5478

import its bindings or make them accessible.

5479

@end defun

5480

5481

@defun eval-in form struct-name

5482

Evaluates @var{form} in the structure named by @var{struct-name}.

5483

Compare this with @code{eval}, which takes a structure object as its

5484

second parameter, not a structure name.

5485

@end defun

5486

5487

@defvar *user-module*

5488

@code{*user-module*} is the default module for human interaction with

5489

Sawfish.

5490

@end defvar

5491

5492

@defun user-eval form

5493

@defunx user-require feature

5494

@code{user-eval} evaluates @code{form} in @code{*user-module*}.

5495

@code{user-require} evaluates @code{(require @var{feature})} in

5496

@code{*user-module*}.

5497

@end defun

5498

5499

@defun quote-menu-item string

5500

Escape any @samp{_} characters in @var{string} such that the result

5501

can be used as the label of a menu item.

5502

@end defun

5503

5504

@defun make-directory-recursively dir

5505

Create directory @var{dir}. Any missing parent directories will also

5506

be created.

5507

@end defun

5508

5509

@defun locate-file filename dirs

5510

Search for a file @var{filename} in any of the directories named by

5511

the list of strings @var{dirs}.

5512

@end defun

5513

5514

@defun clamp x lower upper

5515

Return @var{x} clamped between @var{lower} and @var{upper}. If

5516

@var{x} is less than @var{lower}, return @var{lower}; if it is larger

5517

than @var{upper} return @var{upper}. Otherwise return @var{x}.

5518

@end defun

5519

5520

@defun clamp* x y lower upper

5521

Return the interval (@var{x}, @var{x}+@var{w}) clamped between

5522

@var{lower} and @var{upper}. If @var{x} is less than @var{lower},

5523

return @var{lower}. If @var{x}+@var{w} is larger than @var{upper},

5524

return @var{upper}-@var{w}; this is a value of @var{x} that satisfies

5525

the upper bound, although it may violate the lower bound. Otherwise

5526

return @var{x}.

5527

@end defun

5528

5529

@defun uniquify-list lst

5530

Remove all duplicates values from @var{lst}, using @code{eq}. The

5531

order of elements is not preserved.

5532

@end defun

2673

5533

2674

5534

@node Standard Hooks, Standard Properties, Miscellaneous Functions, Top

2675

5535

@chapter Standard Hooks

2693

5553

the hook is called with arguments @code{(@var{window} . @var{args})}.

2694

5554

@end defun

2695

5555

2696

The following table describes all standard hooks called by Sawfish, and

2697

the arguments they are called with:

2698

2699

@vtable @code

2700

@item pre-command-hook

5556

The available hooks are listed below.

5557

5558

@menu

5559

* Command Hooks::

5560

* Key Hooks::

5561

* Window Construction Hooks::

5562

* Window Destruction Hooks::

5563

* Window Mapping Hooks::

5564

* Window Motion Hooks::

5565

* X Hooks::

5566

* Pointer Motion Hooks::

5567

* Workspace Hooks::

5568

* Startup and Shutdown Hooks::

5569

* Other Hooks::

5570

@end menu

5571

5572

5573

@node Command Hooks, Key Hooks, Standard Hooks, Standard Hooks

5574

@section Command Hooks

5575

@cindex Command Hooks

5576

@cindex Hooks, Command

5577

5578

@defvr {Hook} pre-command-hook

2701

5579

Called before each command is evaluated.

5580

@end defvr

2702

5581

2703

@item post-command-hook

5582

@defvr {Hook} post-command-hook

2704

5583

Called after each command is evaluated.

2705

2706

@item unbound-key-hook

2707

Called when an key or pointer event has been received which there is no

2708

binding for.

2709

2710

@item before-add-window-hook

2711

@itemx add-window-hook

2712

Called with a single window when the window is first adopted by the

2713

window manager. @code{before-add-window-hook} is called first, it

2714

should only set properties of the window.

2715

2716

@item destroy-notify-hook

2717

Called when the window is destroyed. Note that this may be called

2718

asynchronously to the normal event loop. In general, the window manager

2719

will attempt to call this hook as soon after it knows the window has

2720

been destroyed as is possible.

2721

2722

@item map-notify-hook

2723

@itemx unmap-notify-hook

2724

@itemx reparent-notify-hook

2725

@itemx enter-notify-hook

2726

@itemx leave-notify-hook

2727

@itemx focus-in-hook

2728

@itemx focus-out-hook

2729

@itemx shape-notify-hook

2730

Called with a single window argument, analogous to the X events of the

2731

same names.

2732

2733

@item configure-request-hook

2734

Called with two arguments @code{(@var{window} @var{alist})} when an X

2735

@code{ConfigureRequest} event is received. @var{alist} may include

2736

items @code{(stack . above)}, @code{(stack . below)}, @code{(position .

2737

@var{coordinates})}, @code{(dimensions . @var{dimensions})}.

2738

2739

@item enter-frame-part-hook

2740

@itemx leave-frame-part-hook

2741

Called with two arguments, the window and the frame part class

2742

(@pxref{Frame Part Classes}), when the pointer enters or leaves a frame

2743

part.

2744

2745

@item window-moved-hook

2746

@itemx window-resized-hook

2747

Called with a single window argument whenever the window is moved or

2748

resized.

2749

2750

@item visibility-notify-hook

2751

Called with two arguments, the window, and a symbol, one of:

2752

@code{fully-obscured}, @code{partially-obscured}, @code{unobscured}.

2753

2754

@item property-notify-hook

2755

Called with arguments @code{(@var{window} @var{atom-name} @var{type})}

2756

where @var{type} is @code{new-value} or @code{deleted}.

2757

2758

@item client-message-hook

2759

An @code{or} type hook. Called with arguments @code{(@var{window}

2760

@var{type} @var{data-array})}.

2761

2762

@item enter-workspace-hook

2763

@itemx leave-workspace-hook

2764

@itemx workspace-state-change-hook

2765

Called with a single argument: the workspace.

2766

2767

@item add-to-workspace-hook

2768

@itemx remove-from-workspace-hook

2769

Called with a single argument: the window.

2770

2771

@item viewport-resized-hook

5584

@end defvr

5585

5586

5587

@node Key Hooks, Window Construction Hooks, Command Hooks, Standard Hooks

5588

@section Key Hooks

5589

@cindex Key Hooks

5590

@cindex Hooks, Key

5591

5592

@defvr {Hook} unbound-key-hook

5593

Called when an key or pointer event has been received which there is

5594

no binding for. The hook functions return no arguments. This is an

5595

@code{or}-type hookk---the first function that returns non-@code{nil}

5596

will terminate the hook call.

5597

5598

Under normal circumstances, an unbound key release causes a

5599

@code{throw} to top-level. Adding @emph{any} function to this hook

5600

suppresses that behavior.

5601

@end defvr

5602

5603

5604

@node Window Construction Hooks, Window Destruction Hooks, Key Hooks, Standard Hooks

5605

@section Window Construction Hooks

5606

@cindex Window Construction Hooks

5607

@cindex Hooks, Window Construction

5608

5609

@defvr {Window Hook} before-add-window-hook

5610

@defvrx {Window Hook} add-window-hook

5611

Called when the window is first adopted by the window manager. This

5612

occurs before the window is created, installed or placed. At this

5613

early stage, the only safe action is to set properties of the window

5614

(with @code{window-set}).

5615

5616

@code{add-window-hook} is a deprecated hook, replaced by

5617

@code{before-add-window-hook}. It is called immediately after

5618

@code{before-add-window-hook}.

5619

@end defvr

5620

5621

@defvr {Window Hook} after-add-window-hook

5622

Called when the window is first adopted by the window manager. This

5623

occurs after the window has been created, installed and placed.

5624

@end defvr

5625

5626

@defvr {Window Hook} after-framing-hook

5627

Called after a window gets a frame assigned, or after a window's

5628

frame is rebuilt.

5629

@end defvr

5630

5631

5632

@node Window Destruction Hooks, Window Mapping Hooks, Window Construction Hooks, Standard Hooks

5633

@section Window Destruction Hooks

5634

@cindex Window Destruction Hooks

5635

@cindex Hooks, Window Destruction

5636

5637

@defvr {Window Hook} destroy-notify-hook

5638

Called when the window is destroyed. Note that this may be called

5639

asynchronously to the normal event loop. In general, once the window

5640

manager knows the window has been destroyed, it will attempt to call

5641

this hook as soon as possible.

5642

@end defvr

5643

5644

5645

@node Window Mapping Hooks, Window Motion Hooks, Window Destruction Hooks, Standard Hooks

5646

@section Window Mapping Hooks

5647

@cindex Window Mapping Hooks

5648

@cindex Hooks, Window Mapping

5649

5650

@defvr {Window Hook} map-notify-hook

5651

@defvrx {Window Hook} unmap-notify-hook

5652

@defvrx {Window Hook} reparent-notify-hook

5653

@defvrx {Window Hook} shape-notify-hook

5654

Called with a window is mapped, unmapped, reparented, or has its shape

5655

changed, respectively.

5656

5657

Note that iconifying and uniconifying windows triggers unmapping and

5658

mapping, respectively.

5659

@end defvr

5660

5661

@defvr {Window Hook} iconify-window-hook

5662

@defvrx {Window Hook} uniconify-window-hook

5663

@defvrx {Window Hook} shade-window-hook

5664

@defvrx {Window Hook} unshade-window-hook

5665

@defvrx {Window Hook} window-maximized-hook

5666

@defvrx {Window Hook} window-unmaximized-hook

5667

@defvrx {Window Hook} window-depth-change-hook

5668

Called when a window is iconified, uniconified, shaded, unshaded,

5669

maximized, unmaximized, or has its depth changed, respectively.

5670

@end defvr

5671

5672

@defvr {Window Hook} visibility-notify-hook

5673

Called when a window's visibility changes. In addition to the window,

5674

the hook is called one one of the symbols @code{fully-obscured},

5675

@code{partially-obscured}, or @code{unobscured}.

5676

@end defvr

5677

5678

@defvr {Window Hook} place-window-hook

5679

An @code{or}-type hook. Called the first time a window is mapped, or

5680

if the window does not have a true @code{placed} property. This is an

5681

@code{or}-type hook---the first function that returns non-@code{nil}

5682

will terminate the hook call.

5683

@end defvr

5684

5685

5686

@node Window Motion Hooks, X Hooks, Window Mapping Hooks, Standard Hooks

5687

@section Window Motion Hooks

5688

@cindex Window Motion Hooks

5689

@cindex Hooks, Window Motion

5690

5691

@defvr {Window Hook} window-moved-hook

5692

@defvrx Window {Hook} window-resized-hook

5693

Called whenever the window is moved or resized.

5694

5695

This hook is called inside the @code{move-window-to} and

5696

@code{move-resize-window-to} functions, so any operation that moves

5697

the window will trigger this hook. The window motion does not have to

5698

be interactive.

5699

5700

Note that outline window sizing and movement does not use

5701

@code{move-window-to} or @code{move-resize-window-to}, except at the

5702

very end of the operation.

5703

5704

Compare with @code{while-moving-hook} and @code{while-resizing-hook}.

5705

@end defvr

5706

5707

@defvr {Window Hook} before-move-hook

5708

@defvrx {Window Hook} before-resize-hook

5709

Called before starting an interactive move or resize.

5710

@end defvr

5711

5712

@defvr {Window Hook} while-moving-hook

5713

@defvrx {Window Hook} while-resizing-hook

5714

Called during every pointer motion event during a move or resize.

5715

This includes outline window motion. The calls take place before the

5716

window or its outline are actually moved.

5717

5718

Compare with @code{window-moved-hook} and @code{window-resized-hook}.

5719

@end defvr

5720

5721

@defvr {Window Hook} after-move-hook

5722

@defvrx {Window Hook} after-resize-hook

5723

Called after completion of an interactive move or resize. In addition

5724

to the window, the hook is called with a list of symbols indicating how

5725

the window was moved or resized:

5726

@code{horizontal} and @code{vertical} for movement,

5727

@code{right}, @code{left}, @code{bottom} and @code{top} for resizing.

5728

@end defvr

5729

5730

5731

@defvr {Hook} after-restacking-hook

5732

Called after any window restacking operation, including (but possibly

5733

not limited to @code{restack-windows}, @code{x-raise-window} and

5734

@code{x-lower-window}. The hook functions take no arguments.

5735

@end defvr

5736

5737

5738

@node X Hooks, Pointer Motion Hooks, Window Motion Hooks, Standard Hooks

5739

@section X Hooks

5740

@cindex X Hooks

5741

@cindex Hooks, X

5742

5743

@defvr {Window Hook} configure-request-hook

5744

Called when an X

5745

@code{ConfigureRequest} event is received.

5746

In addition to the window, the hook is called with an association list

5747

of configure request properties. This alist may contain items

5748

@code{(stack . above)}, @code{(stack . below)},

5749

@code{(position . @var{coordinates})},

5750

and @code{(dimensions . @var{dimensions})}.

5751

@end defvr

5752

5753

@defvr {Window Hook} property-notify-hook

5754

Called whenever an X window property (not a Sawfish window property)

5755

changes. In addition to the window, the hook is called with the

5756

atom name and one of the symbols @code{new-value} or @code{deleted}.

5757

@end defvr

5758

5759

@defvr {Window Hook} window-state-change-hook

5760

Called whenver certain window manager hints change for a window.

5761

Currently only @code{urgency} is monitored. The hint is an additional

5762

argument to the hook.

5763

@end defvr

5764

5765

5766

@node Pointer Motion Hooks, Workspace Hooks, X Hooks, Standard Hooks

5767

@section Pointer Motion Hooks

5768

@cindex Pointer Motion Hooks

5769

@cindex Hooks, Pointer Motion

5770

5771

In the hooks below, @var{focus-mode} is one of the symbols

5772

@code{normal}, @code{grab} or @code{ungrab}.

5773

5774

@defvr {Window Hook} enter-notify-hook

5775

@defvrx {Window Hook} enter-frame-part-hook

5776

Called when the pointer enters a window (including the root window).

5777

5778

If the window was part of a frame, then @code{enter-frame-part-hook}

5779

is called with three arguments: the window, the frame part class

5780

(@pxref{Frame Part Classes}), and @var{focus-mode}.

5781

5782

Otherwise @code{enter-notify-hook} is called with two arguments: the

5783

window and @var{focus-mode}.

5784

5785

The root window is considered to be a valid window for this hook.

5786

Sawfish will report entering the root window.

5787

@end defvr

5788

5789

@defvr {Window Hook} leave-notify-hook

5790

@defvrx {Window Hook} leave-frame-part-hook

5791

Called when the pointer leaves a window (including the root window).

5792

5793

If the window was part of a frame, then @code{leave-frame-part-hook}

5794

is called with three arguments: the window, the frame part class

5795

(@pxref{Frame Part Classes}), and @var{focus-mode}.

5796

5797

Otherwise @code{leave-notify-hook} is called with two arguments: the

5798

window and @var{focus-mode}.

5799

5800

The root window is considered to be a valid window for this hook.

5801

Sawfish will report leaving the root window.

5802

@end defvr

5803

5804

@defvr {Window Hook} focus-in-hook

5805

Called when focus gains focus. The hook functions take two arguments:

5806

the window that received focus, and @var{focus-mode}.

5807

5808

If your @var{focus-mode} is set to @code{enter-exit}, your window

5809

focus is tightly bound to your pointer position; focus-related hooks

5810

and enter/leave hooks will be called in lockstep. For other values of

5811

@code{focus-mode}, Sawfish will trigger fewer focus-related hook calls

5812

than enter/leave hook calls.

5813

5814

This hook is never called for the root window, because the root window

5815

never gets focus.

5816

@end defvr

5817

5818

@defvr {Window Hook} focus-out-hook

5819

Called when a window loses focus. The hook functions take two

5820

arguments: the window that lost focus, and @var{focus-mode}.

5821

5822

If your @var{focus-mode} is set to @code{enter-exit}, your window

5823

focus is tightly bound to your pointer position; focus-related hooks

5824

and enter/leave hooks will be called in lockstep. For other values of

5825

@code{focus-mode}, Sawfish will trigger fewer focus-related hook calls

5826

than enter/leave hook calls.

5827

5828

This hook is never called for the root window, because the root window

5829

never gets focus.

5830

@end defvr

5831

5832

5833

@node Workspace Hooks, Startup and Shutdown Hooks, Pointer Motion Hooks, Standard Hooks

5834

@section Workspace Hooks

5835

@cindex Workspace Hooks

5836

@cindex Hooks, Workspace

5837

5838

@defvr {Hook} enter-workspace-hook

5839

@defvrx {Hook} leave-workspace-hook

5840

Called when switching from one workspace to another. This includes

5841

switching caused by adding or removing a workspace. The hook is

5842

called with a @emph{list} containing the workspace in question.

5843

@end defvr

5844

5845

@defvr {Window Hook} add-to-workspace-hook

5846

@defvrx {Window Hook} remove-from-workspace-hook

5847

Called when a window is added or removed from a workspace. In

5848

addition to the window, the hook is called with a @emph{list}

5849

containing the workspace being changed. If the window is in multiple

5850

workspaces, then removing triggers @code{remove-from-workspace-hook}

5851

for each workspace.

5852

@end defvr

5853

5854

@defvr {Hook} workspace-state-change-hook

5855

Called when any aspect of the workspaces change, including adding a

5856

workspace, removing a workspace, moving a workspace, inserting or

5857

removing a window from a workspace, etc. This hook is called with no

5858

arguments, so you should use one of the more specific hooks if

5859

possible.

5860

@end defvr

5861

5862

@defvr {Hook} viewport-resized-hook

2772

5863

Called when the number of rows and columns in each virtual workspace is

2773

5864

changed.

5865

@end defvr

2774

5866

2775

@item viewport-moved-hook

5867

@defvr {Hook} viewport-moved-hook

2776

5868

Called when the origin of the viewport into the virtual workspace is

2777

5869

moved.

2778

2779

@item place-window-hook

2780

An @code{or} type hook. Called the first a window is mapped.

2781

2782

@item window-state-change-hook

2783

@itemx iconify-window-hook

2784

@itemx uniconify-window-hook

2785

@itemx shade-window-hook

2786

@itemx unshade-window-hook

2787

@itemx window-maximized-hook

2788

@itemx window-unmaximized-hook

2789

@itemx window-depth-change-hook

2790

Called with a single window.

2791

2792

@item after-initialization-hook

5870

@end defvr

5871

5872

@defvr {Hook} enter-flipper-hook

5873

@defvrx {Hook} leave-flipper-hook

5874

When viewport edge-flipping is enabled, these hooks are called as the

5875

pointer enters and leaves the pixel-wide border on the edge of the

5876

screen. They're called with a single argument, one of the symbols

5877

@code{left}, @code{right}, @code{top}, @code{bottom} indicating the

5878

edge in question.

5879

@end defvr

5880

5881

5882

@node Startup and Shutdown Hooks, Other Hooks, Workspace Hooks, Standard Hooks

5883

@section Startup and Shutdown Hooks

5884

@cindex Startup and Shutdown Hooks

5885

@cindex Hooks, Startup and Shutdown

5886

5887

@defvr {Hook} after-initialization-hook

2793

5888

Called after adopting the initial set of windows.

2794

2795

@item before-exit-hook

5889

@end defvr

5890

5891

@defvr {Window Hook} remove-window-hook

5892

Called on each window as Sawfish shuts down (possibly for a restart).

5893

The hook functions take no arguments.

5894

@end defvr

5895

5896

@defvr {Hook} before-exit-hook

2796

5897

Called immediately before exiting.

5898

@end defvr

2797

5899

2798

@item sm-window-save-functions

2799

@itemx sm-restore-window-hook

2800

@itemx sm-after-restore-hook

5900

@defvr {Hook} sm-window-save-functions

5901

@defvrx {Hook} sm-restore-window-hook

5902

@defvrx {Hook} sm-after-restore-hook

2801

5903

Session management hooks, @ref{Session Management}.

2802

2803

@item before-move-hook

2804

@itemx before-resize-hook

2805

Called before starting an interactive move or resize, with a single

2806

argument: the window.

2807

2808

@item while-moving-hook

2809

@itemx while-resizing-hook

2810

Called while interactively moving or resizing the window passed as the

2811

argument to the hook.

2812

2813

@item after-move-hook

2814

@itemx after-resize-hook

2815

Called after completion of an interactive move or resize. Called with

2816

two arguments: the window, and a list of symbols defining how the

2817

window was moved or resized.

2818

2819

@item gtkrc-changed-hook

5904

@end defvr

5905

5906

5907

@node Other Hooks, , Startup and Shutdown Hooks, Standard Hooks

5908

@section Other Hooks

5909

@cindex Other Hooks

5910

@cindex Hooks, Other

5911

5912

@defvr {Hook} gtkrc-changed-hook

2820

5913

When using the @code{gtkrc} module to load the current gtk style

2821

5914

parameters, this hook is called when the style changes.

2822

2823

@item enter-flipper-hook

2824

@itemx leave-flipper-hook

2825

When viewport edge-flipping is enabled, these hooks are called as the

2826

pointer enters and leaves the pixel-wide border on the edge of the

2827

screen. They're called with a single argument, one of the symbols

2828

@code{left}, @code{right}, @code{top}, @code{bottom} defining the edge

2829

in question.

2830

2831

@end vtable

5915

@end defvr

5916

5917

@defvr {Window Hook} client-message-hook

5918

Called with arguments @code{(@var{window} @var{type}

5919

@var{data-array})}. This is an @code{or}-type hook---the first

5920

function that returns non-@code{nil} will terminate the hook call.

5921

@end defvr

2832

5922

2833

5923

2834

5924

@node Standard Properties, Session Management, Standard Hooks, Top

2949

6039

There are two methods of doing this. If the module only wants to save

2950

6040

and restore the values of properties in each window's property list

2951

6041

(i.e. those values set via @code{window-put}), then the following

2952

function may be used:

6042

functions may be used:

2953

6043

2954

6044

@defun sm-add-saved-properties &rest properties

2955

Arrange for all symbols @var{properties} to be saved and loaded with

6045

@defunx sm-add-restored-properties &rest properties

6046

Arrange for all symbols @var{properties} to be saved or restored with

2956

6047

the session.

2957

6048

@end defun

2958

6049

6050

@defvar sm-saved-window-properties

6051

@defvarx sm-restored-window-properties

6052

Lists of properties (symbols) to be saved or restored with each

6053

session.

6054

@end defvar

6055

2959

6056

If a Lisp module chooses to use this method it may add a function to

2960

6057

the @code{add-window-hook} to act on the reloaded properties when the

2961

6058

session is reloaded.

2986

6083

Hook called after loading a saved session.

2987

6084

@end defvar

2988

6085

6086

@defvar sm-save-directory

6087

The directory that will contain all Sawfish sessions. It must be a

6088

string. By default it is @code{"~/.sawfish/sessions"}.

6089

@end defvar

6090

6091

@defvar sm-sloppy-id-matching

6092

When loading sessions, the algorithm that matches saved session data

6093

to running clients requires that if one has a session id, then so must

6094

the other, and they must match. Setting this variable to true turns

6095

that feature off, allowing some broken clients to be session managed.

6096

Defaults to false.

6097

@end defvar

6098

2989

6099

2990

6100

@node FAQ, Function Index, Session Management, Top

2991

6101