Window/photo command C reference
See Window and photo command implementation for ownership, failure and platform boundaries. These are private implementation interfaces.
- group Window and photo command internals
Private command/canvas callbacks, not installed C APIs.
Functions
-
static int GetRealizedWindow(Tcl_Interp *interp, const char *string, Tk_Window *tkwinPtr)
Resolve a Tk path and ensure its native window exists.
Borrow the interpreter and return a borrowed Tk_Window through tkwinPtr on success. Realization does not map the window. Return TCL_ERROR from path lookup without assigning the output.
- Parameters:
interp – [inout] Borrowed interpreter receiving command results and error diagnostics.
string – [in] Borrowed NUL-terminated Tk window pathname.
tkwinPtr – [out] Required output receiving a borrowed realized Tk window only on success.
-
static Window StringToWindow(Tcl_Interp *interp, const char *string)
Resolve a Tk path or legacy integer native-window identifier.
Tk toplevel paths select their wrapper through Rbc_GetRealWindowId(). Numeric input uses Tcl_GetInt, not a pointer-width parser; Windows wraps that value with Rbc_WinWindowFromHWND(). Return None on lookup or conversion failure. The result does not transfer ownership of the window.
- Parameters:
interp – [inout] Borrowed interpreter receiving command results and error diagnostics.
string – [in] Borrowed NUL-terminated Tk path or native ID text, as described above.
-
static int XGeometryErrorProc(ClientData clientData, XErrorEvent *errEventPtr)
Record an XGetGeometry protocol error.
clientData points to the caller-owned integer flag while the temporary Tk error handler is installed. Set it to TCL_ERROR and return zero to consume the error. Do not retain the flag or event pointer.
- Parameters:
clientData – [inout] Borrowed pointer to the stack-backed integer error flag, set to TCL_ERROR.
errEventPtr – [in] Borrowed X protocol-error event; not retained.
-
static int GetWindowSize(Tcl_Interp *interp, Window window, int *widthPtr, int *heightPtr)
Query X11 drawable dimensions with a scoped protocol-error handler.
Borrow the interpreter and its main-window display. Synchronize the X connection before removing the temporary X_GetGeometry error handler, so its stack-backed error flag remains valid. Return TCL_ERROR on query or protocol failure, or dimensions exceeding INT_MAX; only the overflow case sets a diagnostic here. Publish both output dimensions only on success.
- Parameters:
interp – [inout] Borrowed interpreter receiving command results and error diagnostics.
window – [in] Borrowed Tk-compatible native window identifier.
widthPtr – [out] Required output receiving native window width only on success.
heightPtr – [out] Required output receiving native window height only on success.
-
static int ColormapOp(ClientData clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Inspect allocated cells in the legacy X11 colormap range.
Resolve and realize the Tk path in objv[2]. Probe up to 256 writable cells, release the allocated cells, then query pixel IDs 0 through 255. Return alternating RGB strings and pixel IDs for cells not obtained by the probe. This legacy algorithm assumes an indexed colormap with allocated pixel IDs below 256; it is not a general visual enumerator.
- Parameters:
clientData – [in] Dispatch client data; unused by this handler.
interp – [inout] Borrowed interpreter receiving command results and error diagnostics.
objc – [in] Number of borrowed command arguments, including command and operation names.
objv – [in] Borrowed Tcl argument array; operation-specific positions are described above.
-
static int LowerOp(ClientData clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Lower each named Tk window in argument order.
Resolve objv[2..objc-1] relative to the interpreter main window and request Below stacking with no sibling. Return TCL_ERROR on a failed lookup, retaining any earlier restacking. The Tk_RestackWindow return status is not propagated. An empty window list succeeds.
- Parameters:
clientData – [in] Dispatch client data; unused by this handler.
interp – [inout] Borrowed interpreter receiving command results and error diagnostics.
objc – [in] Number of borrowed command arguments, including command and operation names.
objv – [in] Borrowed Tcl argument array; operation-specific positions are described above.
-
static int RaiseOp(ClientData clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Raise each named Tk window in argument order.
Resolve objv[2..objc-1] relative to the interpreter main window and request Above stacking with no sibling. Return TCL_ERROR on a failed lookup, retaining any earlier restacking. The Tk_RestackWindow return status is not propagated. An empty window list succeeds.
- Parameters:
clientData – [in] Dispatch client data; unused by this handler.
interp – [inout] Borrowed interpreter receiving command results and error diagnostics.
objc – [in] Number of borrowed command arguments, including command and operation names.
objv – [in] Borrowed Tcl argument array; operation-specific positions are described above.
-
static int MapOp(ClientData clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Request native mapping for each path or legacy integer ID.
For Tk paths, realize the window, set TK_MAPPED through Tk_FakeWin, and use its client window ID. Numeric arguments are parsed with Tcl_GetInt and cast directly to Window, without StringToWindow. Issue XMapWindow requests in argument order; later conversion errors do not undo earlier requests. This path does not call Tk_MapWindow.
- Parameters:
clientData – [in] Dispatch client data; unused by this handler.
interp – [inout] Borrowed interpreter receiving command results and error diagnostics.
objc – [in] Number of borrowed command arguments, including command and operation names.
objv – [in] Borrowed Tcl argument array; operation-specific positions are described above.
-
static int MoveOp(ClientData clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Move a named Tk window using screen-distance arguments.
Borrow the window resolved from objv[2]. Convert objv[3] and objv[4] with Tk_GetPixelsFromObj before moving; append an axis-specific diagnostic on conversion failure. Tk_MoveWindow uses parent-relative pixel coordinates, not graph coordinates or an explicit toplevel wrapper.
- Parameters:
clientData – [in] Dispatch client data; unused by this handler.
interp – [inout] Borrowed interpreter receiving command results and error diagnostics.
objc – [in] Number of borrowed command arguments, including command and operation names.
objv – [in] Borrowed Tcl argument array; operation-specific positions are described above.
-
static int UnmapOp(ClientData clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Request native unmapping for each path or legacy integer ID.
For Tk paths, realize the window, clear TK_MAPPED through Tk_FakeWin, and use its client window ID. Numeric arguments are parsed with Tcl_GetInt and cast directly to Window, without StringToWindow. Issue XUnmapWindow requests in argument order; later conversion errors do not undo earlier requests. This path does not call Tk_UnmapWindow.
- Parameters:
clientData – [in] Dispatch client data; unused by this handler.
interp – [inout] Borrowed interpreter receiving command results and error diagnostics.
objc – [in] Number of borrowed command arguments, including command and operation names.
objv – [in] Borrowed Tcl argument array; operation-specific positions are described above.
-
static int ChangesOp(ClientData clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Request backing-store and save-under attributes for a toplevel.
Resolve and realize objv[2]. For a toplevel, obtain its real native window ID and issue XChangeWindowAttributes with WhenMapped backing store and save_under enabled. A child window is a successful no-op. TCL_OK reports request submission, not server acceptance of the hints.
- Parameters:
clientData – [in] Dispatch client data; unused by this handler.
interp – [inout] Borrowed interpreter receiving command results and error diagnostics.
objc – [in] Number of borrowed command arguments, including command and operation names.
objv – [in] Borrowed Tcl argument array; operation-specific positions are described above.
-
static int QueryOp(ClientData clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Return the pointer position in root coordinates when available.
clientData is the borrowed Tk main window. Query its display and window ID; on success set the Tcl result to @x,y using root coordinates. A false XQueryPointer result leaves the interpreter result unchanged and still returns TCL_OK. objc and objv are unused.
- Parameters:
clientData – [in] Borrowed Tk main window supplied by dispatch.
interp – [inout] Borrowed interpreter receiving command results and error diagnostics.
objc – [in] Unused query argument; direct internal calls may supply zero/NULL.
objv – [in] Unused query argument; direct internal calls may supply zero/NULL.
-
static int WarpToOp(ClientData clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Optionally warp the pointer, then query its root position.
With no target, delegate directly to QueryOp. An @x,y target is parsed by Rbc_GetXY and uses the main window screen root; otherwise resolve and realize a Tk path, reject an unmapped window, and target its integer center. Native warping can generate pointer events; no Tcl event loop is run here. Return parsing/lookup errors or the subsequent query status.
- Parameters:
clientData – [in] Borrowed Tk main window supplied by dispatch.
interp – [inout] Borrowed interpreter receiving command results and error diagnostics.
objc – [in] Number of borrowed command arguments, including command and operation names.
objv – [in] Borrowed Tcl argument array; operation-specific positions are described above.
-
static int ConvolveOp(ClientData clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Convolve an existing photo into an existing destination photo.
Require a nonempty square list of finite kernel values with a finite sum. Own and free the kernel and copied color buffers locally; photo handles are borrowed. The source is copied before destination publication. Parse failures return TCL_ERROR. Photo publication uses the void color-image helper and is not an atomic transaction with rollback.
- Parameters:
clientData – [in] Dispatch client data; unused by this handler.
interp – [inout] Borrowed interpreter receiving command results and error diagnostics.
objc – [in] Number of borrowed command arguments, including command and operation names.
objv – [in] Borrowed Tcl argument array; operation-specific positions are described above.
-
static int QuantizeOp(ClientData clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Quantize a copied photo with a palette of one to 256 colors.
Borrow both photo handles and free both color buffers after the quantizer returns. Resize the destination to the source dimensions before parsing the optional color count; an error therefore need not leave it unchanged. Source dimensions of one pixel or less are rejected.
- Parameters:
clientData – [in] Dispatch client data; unused by this handler.
interp – [inout] Borrowed interpreter receiving command results and error diagnostics.
objc – [in] Number of borrowed command arguments, including command and operation names.
objv – [in] Borrowed Tcl argument array; operation-specific positions are described above.
-
static int ReadJPEGOp(ClientData clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Decode a JPEG file into an existing photo when enabled.
The direct and normalized nested dispatch forms place the file name in objv[2] and destination photo name in objv[3]. Borrow the photo handle and return Rbc_JPEGToPhoto status. Without HAVE_JPEGLIB_H, return TCL_ERROR with the unsupported diagnostic without looking up the photo.
- Parameters:
clientData – [in] Dispatch client data; unused by this handler.
interp – [inout] Borrowed interpreter receiving command results and error diagnostics.
objc – [in] Number of borrowed command arguments, including command and operation names.
objv – [in] Borrowed Tcl argument array; operation-specific positions are described above.
-
static int GradientOp(ClientData clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Fill an existing photo with a legacy procedural gradient.
Borrow the destination photo and use its current dimensions. Acquire both Tk colors, create temporary color pixels, and select the type from objv[5]. Release both color references and pixel storage on completion or an invalid type. Linear, radial and rectangular modes consume random values; blank writes opaque white but still validates both colors. Publication uses the void Rbc_ColorImageToPhoto helper, so TCL_OK does not propagate lower-level photo-write status.
- Parameters:
clientData – [in] Dispatch client data; unused by this handler.
interp – [inout] Borrowed interpreter receiving command results and error diagnostics.
objc – [in] Number of borrowed command arguments, including command and operation names.
objv – [in] Borrowed Tcl argument array; operation-specific positions are described above.
-
static int ResampleOp(ClientData clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Resize a photo according to the destination photo dimensions.
Borrow existing photos and filter descriptors. A destination dimension of one pixel or less causes a source-size copy; equal dimensions also copy. The default filter is none. A vertical filter is parsed only when the first filter resolves to a non-NULL descriptor. Lower photo-write return values are not uniformly propagated by this legacy command.
- Parameters:
clientData – [in] Dispatch client data; unused by this handler.
interp – [inout] Borrowed interpreter receiving command results and error diagnostics.
objc – [in] Number of borrowed command arguments, including command and operation names.
objv – [in] Borrowed Tcl argument array; operation-specific positions are described above.
-
static int RotateOp(ClientData clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Rotate a copied photo by a finite Tcl expression angle in degrees.
Validate names, preserve the interpreter across angle evaluation, then reacquire both photo handles before accessing pixels. Reject deleted photos or destroyed Tk state; same-name replacements are used. Allocate and release source/rotated buffers locally. Photo publication is not a rollback transaction.
- Parameters:
clientData – [in] Dispatch client data; unused by this handler.
interp – [inout] Borrowed interpreter receiving command results and error diagnostics.
objc – [in] Number of borrowed command arguments, including command and operation names.
objv – [in] Borrowed Tcl argument array; operation-specific positions are described above.
-
static int SnapOp(ClientData clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Capture a native window into a named photo, optionally resizing it.
For a Tk path, capture the client drawable and its Tk dimensions rather than the window-manager wrapper. Numeric input uses StringToWindow() and native geometry. Borrow all windows and delegate capture and destination lookup to Rbc_SnapPhoto(); return its Tcl status. This is screen capture, not graph remapping or vector-document export.
- Parameters:
clientData – [in] Dispatch client data; unused by this handler.
interp – [inout] Borrowed interpreter receiving command results and error diagnostics.
objc – [in] Number of borrowed command arguments, including command and operation names.
objv – [in] Borrowed Tcl argument array; operation-specific positions are described above.
-
static int SubsampleOp(ClientData clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Resize a validated source-photo rectangle into a destination photo.
Require nonnegative origin, positive extent and a rectangle inside the source. An effectively empty destination takes the region dimensions. Default to the box filter; none selects the unfiltered resize path. Photos and filters are borrowed, and the command neither creates nor deletes the destination photo.
- Parameters:
clientData – [in] Borrowed Tk main window supplied by dispatch.
interp – [inout] Borrowed interpreter receiving command results and error diagnostics.
objc – [in] Number of borrowed command arguments, including command and operation names.
objv – [in] Borrowed Tcl argument array; operation-specific positions are described above.
-
static int ImageOp(ClientData clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Dispatch nested winop image operations using direct-operation indices.
Validate against imageOps, then pass objc - 1 and objv + 1 so shared handlers see source and destination at their original argument positions. Tables for direct and nested operations are intentionally not identical.
- Parameters:
clientData – [in] Unused dispatch data; nested dispatch obtains the current main window.
interp – [inout] Borrowed interpreter receiving command results and error diagnostics.
objc – [in] Number of borrowed command arguments, including command and operation names.
objv – [in] Borrowed Tcl argument array; operation-specific positions are described above.
-
static int WinopCmd(ClientData clientData, Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const objv[])
Dispatch a stateless winop request with the current Tk main window.
Validate operation and arity through winOps before calling its handler. No per-command heap object or command deletion callback is maintained.
- Parameters:
clientData – [in] Dispatch client data; unused by this handler.
interp – [inout] Borrowed interpreter receiving command results and error diagnostics.
objc – [in] Number of borrowed command arguments, including command and operation names.
objv – [in] Borrowed Tcl argument array; operation-specific positions are described above.
-
int Rbc_WinopInit(Tcl_Interp *interp)
Register the rbc::winop Tcl object command.
Returns TCL_OK. Registers the static dispatcher without client data or a delete callback; does not create a window.
- Parameters:
interp – [inout] Borrowed interpreter with the RBC namespace and Tk initialized; see Interpreter arguments.
-
static int GetRealizedWindow(Tcl_Interp *interp, const char *string, Tk_Window *tkwinPtr)
Data records and member contracts
These records describe stored state and resource ownership. Their presence in the reference does not make private layouts part of the installed C API.
-
struct WinopOpSpec
Typed command dispatch entry with shared argument validation metadata.
Public Members
-
Rbc_OpSpecHeader header
Operation name, total argument bounds and usage suffix.
-
RbcWinOp *proc
Typed command handler for this operation.
-
Rbc_OpSpecHeader header