tk/doc/GetPixels.3

   1 '\"
   2 '\" Copyright (c) 1990 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1998 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 '\" RCS: @(#) $Id$
   9 '\"
  10 .so man.macros
  11 .TH Tk_GetPixelsFromObj 3 8.1 Tk "Tk Library Procedures"
  12 .BS
  13 .SH NAME
  14 Tk_GetPixelsFromObj, Tk_GetPixels, Tk_GetMMFromObj, Tk_GetScreenMM \- translate between strings and screen units
  15 .SH SYNOPSIS
  16 .nf
  17 \fB#include <tk.h>\fR
  18 .sp
  19 .VS 8.1
  20 int
  21 \fBTk_GetPixelsFromObj(\fIinterp, tkwin, objPtr, intPtr\fB)\fR
  22 .VE
  23 .sp
  24 int
  25 \fBTk_GetPixels(\fIinterp, tkwin, string, intPtr\fB)\fR
  26 .sp
  27 .VS 8.1
  28 int
  29 \fBTk_GetMMFromObj(\fIinterp, tkwin, objPtr, doublePtr\fB)\fR
  30 .VE
  31 .sp
  32 int
  33 \fBTk_GetScreenMM(\fIinterp, tkwin, string, doublePtr\fB)\fR
  34 .SH ARGUMENTS
  35 .AS "Tcl_Interp" *joinPtr
  36 .AP Tcl_Interp *interp in
  37 Interpreter to use for error reporting.
  38 .AP Tk_Window tkwin in
  39 Window whose screen geometry determines the conversion between absolute
  40 units and pixels.
  41 .VS 8.1 br
  42 .AP Tcl_Obj *objPtr in/out
  43 String value specifies a distance on the screen;
  44 internal rep will be modified to cache converted distance.
  45 .AP "CONST char" *string in
  46 Same as \fIobjPtr\fR except specification of distance is passed as
  47 a string.
  48 .VE
  49 .AP int *intPtr out
  50 Pointer to location in which to store converted distance in pixels.
  51 .AP double *doublePtr out
  52 Pointer to location in which to store converted distance in millimeters.
  53 .BE
  54
  55 .SH DESCRIPTION
  56 .PP
  57 These procedures take as argument a specification of distance on
  58 .VS 8.1
  59 the screen (\fIobjPtr\fR or \fIstring\fR) and compute the
  60 .VE
  61 corresponding distance either in integer pixels or floating-point millimeters.
  62 In either case,
  63 .VS 8.1
  64 \fIobjPtr\fR or \fIstring\fR
  65 .VE
  66 specifies a screen distance as a
  67 floating-point number followed by one of the following characters
  68 that indicates units:
  69 .TP
  70 <none>
  71 The number specifies a distance in pixels.
  72 .TP
  73 \fBc\fR
  74 The number specifies a distance in centimeters on the screen.
  75 .TP
  76 \fBi\fR
  77 The number specifies a distance in inches on the screen.
  78 .TP
  79 \fBm\fR
  80 The number specifies a distance in millimeters on the screen.
  81 .TP
  82 \fBp\fR
  83 The number specifies a distance in printer's points (1/72 inch)
  84 on the screen.
  85 .PP
  86 .VS 8.1
  87 \fBTk_GetPixelsFromObj\fR converts the value of \fIobjPtr\fR to the
  88 nearest even number of pixels and stores that value at \fI*intPtr\fR.
  89 It returns \fBTCL_OK\fR under normal circumstances.
  90 If an error occurs (e.g. \fIobjPtr\fR contains a number followed
  91 by a character that isn't one of the ones above) then
  92 \fBTCL_ERROR\fR is returned and an error message is left
  93 in \fIinterp\fR's result if \fIinterp\fR isn't NULL.
  94 \fBTk_GetPixelsFromObj\fR caches information about the return
  95 value in \fIobjPtr\fR, which speeds up future calls to
  96 \fBTk_GetPixelsFromObj\fR with the same \fIobjPtr\fR.
  97 .PP
  98 \fBTk_GetPixels\fR is identical to \fBTk_GetPixelsFromObj\fR except
  99 that the screen distance is specified with a string instead
 100 of an object.  This prevents \fBTk_GetPixels\fR from caching the
 101 return value, so \fBTk_GetAnchor\fR is less efficient than
 102 \fBTk_GetPixelsFromObj\fR.
 103 .PP
 104 \fBTk_GetMMFromObj\fR and \fBTk_GetScreenMM\fR are similar to
 105 \fBTk_GetPixelsFromObj\fR and \fBTk_GetPixels\fR (respectively) except
 106 that they convert the screen distance to millimeters and
 107 store a double-precision floating-point result at \fI*doublePtr\fR.
 108 .VE
 109
 110 .SH KEYWORDS
 111 centimeters, convert, inches, millimeters, pixels, points, screen units