source: trunk/SRC/ToBeReviewed/STRING/str_size.pro @ 226

;+
;
; @file_comments
; The purpose of this function is to return the proper
; character size to make a specified string a specified
; width in a window. The width is specified in normalized
; coordinates. The function is extremely useful for sizing
; strings and labels in resizeable graphics windows.
;
; @categories
; Graphics, Widget
;
; @param STRING {in}{required}
; This is the string that you want to make a specified
; target size or width.
;
; @param TARGETWIDTH {in}{optional}{default=0.25}
; This is the target width of the string in normalized
; coordinates in the current graphics window. The character
; size of the string (returned as thisCharSize) will be
; calculated to get the string width as close as possible to
; the target width.
;
; @keyword INITSIZE {default=1.0}
; This is the initial size of the string. Default is 1.0.
;
; @keyword STEP{default=0.05}
; This is the amount the string size will change in each step
; of the interactive process of calculating the string size.
;
; @returns
; thisCharSize. This is the size the specified string should be set
; to if you want to produce output of the specified target
; width. The value is in standard character size units where
; 1.0 is the standard character size.
;
; @examples
; To make the string "Happy Holidays" take up 30% of the width of
; the current graphics window, type this:
;
;   XYOUTS, 0.5, 0.5, ALIGN=0.5, "Happy Holidays", $
;   CHARSIZE=STR_SIZE("Happy Holidays", 0.3)
;
; @history
; Written by: David Fanning, 17 DEC 96.
; Added a scaling factor to take into account the aspect ratio
; of the window in determining the character size. 28 Oct 97. DWF
;
; @version
; $Id$
;
;-

FUNCTION str_size, string, targetWidth, INITSIZE=initsize, STEP=step
;
  compile_opt idl2, strictarrsubs
;

ON_ERROR, 1

   ; Check positional parameters.

np = N_PARAMS()
CASE np OF
   0: MESSAGE, 'One string parameter is required.'
   1: targetWidth = 0.25
   ELSE:
ENDCASE

   ; Check keywords. Assign default values.

IF N_ELEMENTS(step) EQ 0 THEN step = 0.05
IF N_ELEMENTS(initsize) EQ 0 THEN initsize = 1.0

   ; Calculate a trial width.

size = initsize
XYOUTS, 0.5, 0.5, ALIGN=0.5, string, WIDTH=thisWidth, $
      CHARSIZE=-size, /NORMAL

   ; Size is perfect.

IF thisWidth EQ targetWidth THEN RETURN, size * Float(!D.Y_Size)/!D.X_Size

   ; Initial size is too big.

IF thisWidth GT targetWidth THEN BEGIN
   REPEAT BEGIN
     XYOUTS, 0.5, 0.5, ALIGN=0.5, string, WIDTH=thisWidth, $
        CHARSIZE=-size, /NORMAL
      size = size - step
   ENDREP UNTIL thisWidth LE targetWidth
   RETURN, size * Float(!D.Y_Size)/!D.X_Size
ENDIF

   ; Initial size is too small.

IF thisWidth LT targetWidth THEN BEGIN
   REPEAT BEGIN
     XYOUTS, 0.5, 0.5, ALIGN=0.5, string, WIDTH=thisWidth, $
        CHARSIZE=-size, /NORMAL
      size = size + step
   ENDREP UNTIL thisWidth GT targetWidth
   size = size - step ; Need a value slightly smaller than target.
   RETURN, size * Float(!D.Y_Size)/!D.X_Size
ENDIF

END