#                    H E L P P A G E . I T K
# BRL-CAD
#
# Copyright (c) 2004-2016 United States Government as represented by
# the U.S. Army Research Laboratory.
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public License
# version 2.1 as published by the Free Software Foundation.
#
# This library is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this file; see the file named COPYING for more
# information.
#
###
#
# This file provides a page that can be used for providing a general
# overview of the picture making process.
#

package require Itcl
package require Itk
package require Iwidgets

namespace eval RtWizard {

    package provide HelpPage 1.0

    #
    # helppage - Provides a lowercased access method for the
    #            HelpPage class
    #
    proc helppage {pathName args} {
	uplevel HelpPage $pathName $args
    }

    #
    # Add options
    #
    option add *HelpPage.borderWidth 2 widgetDefault
    option add *HelpPage.labelPos wn widgetDefault
    option add *HelpPage.listHeight 150 widgetDefault
    option add *HelpPage.hscrollMode dynamic widgetDefault
    option add *HelpPage.vscrollMode dynamic widgetDefault
    option add *HelpPage.textBackground #ccccff
    option add *HelpPage.helpText "Bananas are tasty." widgetDefault

    #
    # Define the usual options
    #
    ::itk::usual HelpPage {
	keep    -background \
	    -borderwidth \
	    -cursor \
	    -elementborderwidth \
	    -foreground \
	    -highlightcolor \
	    -highlightthickness \
	    -insertbackground \
	    -insertborderwidth \
	    -insertofftime \
	    -insertontime \
	    -insertwidth \
	    -jump \
	    -labelfont \
	    -selectbackground \
	    -selectborderwidth \
	    -textbackground \
	    -textfont \
	    -troughcolor \
	    -stepName
    }

    #
    # HelpPage
    #
    # The helppage holds helpful text
    #
    ::itcl::class HelpPage {
	inherit ::iwidgets::Labeledframe

	#
	# Configuration variables
	#
	itk_option define -helpText helptext HelpText ""

	public {
	    #
	    # methods
	    #
	    constructor {args} {};

	    method onSelect {}
	    method onDeselect {}
	    method getStepInfo {}
	}


	private {
	    #
	    # methods
	    #
	    method doHelpText {}

	    #
	    # variables
	    #
	}
    }

    #--------------------#
    #   Public Methods   #
    #--------------------#
    #
    # constructor - builds the Help Page
    #
    ::itcl::body HelpPage::constructor {args} {

	#
	# Set up the childsite
	#
	set cs [ $this childsite ]
	$cs configure -relief groove -bd 2

	#
	# Splat instructive text.
	#
	itk_component add helpPanel {
	    ::iwidgets::scrolledtext $cs.gp \
		-vscrollmode dynamic \
		-hscrollmode dynamic \
		-wrap word \
		-visibleitems 80x30 \
		-textfont {helvetica 10} \
		-relief flat

	} {
	    usual
	    ignore -textfont
	}

	#
	# Pack it!
	#
	pack $itk_component(helpPanel) -fill both -expand 1

	#
	# Evaluate any additional args.
	#
	eval itk_initialize $args

	doHelpText
    }

    #
    # helpText
    #
    ::itcl::configbody HelpPage::helpText {
	$itk_component(helpPanel) configure -state normal
	$itk_component(helpPanel) insert end [cget -helpText]
	$itk_component(helpPanel) configure -state disabled
    }

    #
    # onSelect
    #
    # Makes any necessary changes to the Wizard configuration
    # when this page is selected.
    #
    ::itcl::body HelpPage::onSelect {} {
	#
	# Nothing yet!
	#
    }

    #
    # onDeselect
    #
    # Cleans up when the page is deselected
    #
    ::itcl::body HelpPage::onDeselect {} {
	#
	# Nothing yet!
	#
    }

    #
    # getStepInfo
    #
    # In principal, returns a name for the step, and a variable that
    # can be queried for state. The Help page is not a 'step',
    # so it returns "No Step"
    #
    ::itcl::body HelpPage::getStepInfo {} {
	set a "No Step"
	set b "banana"
	return [list $a $b]
    }

    #--------------------#
    #  Private Methods   #
    #--------------------#
    #
    itcl::body HelpPage::doHelpText {} {

	#
	# A short alias for convenience,
	#
	set t $itk_component(helpPanel)

	$t configure -state normal

	$t insert insert \
	    "Overview\n\n" \
	    Level1Tag

	$t insert insert \
	    "Welcome to the RtWizard. The RtWizard is a tool for creating images from BRL-CAD databases. The design philosophy behind the RtWizard is to provide you, the user, with a choice of several image types. Once the selection is made, you need only configure a minimum of options before a picture can be made. The user is then free to tweak options and generate new images.\n\n" \
	    NormalTag

	$t insert insert \
	    "The Database Selection Page\n\n" \
	    Level1Tag

	$t insert insert \
	    "If RtWizard is started without specifying a BRL-CAD database on the command line, you are first presented with the database selection page. Use the file browser on the page to find the desired BRL-CAD database. Once you have selected the desired file, press the okay button.\n\n" \
	    NormalTag

	$t insert insert \
	    "Note that it is current not possible to change the BRL-CAD database once one has been opened.\n\n" \
	    NormalTag

	$t insert insert \
	    "The Sample Image Page\n\n" \
	    Level1Tag

	$t insert insert \
	    "Once the database has been selected, you will be presented with the sample images page. This page allows you to select the type of image you would like to produce. On the left is a widget that allows you to select the type of image. Below that widget is some text that describes the image and what information will be required. To the right is the sample image. To proceed, simply select the image you would like to make and hit \"OK\" \n\n" \
	    NormalTag

	$t insert insert \
	    "The image type can be changed at any time by selecting the \"New Image\" control from the Image menu. You may also select an image type directly from the Image menu. Note that if you change image types during production, any data that is common between the two image types will be conserved.\n\n" \
	    NormalTag

	$t insert insert \
	    "The Steps\n\n" \
	    Level1Tag

	$t insert insert \
	    "Use the Steps menu to move between steps. They may be done in any order.\n\n" \
	    NormalTag

	$t insert insert \
	    "When you select an image type, RtWizard will present you with a series of steps. These steps are listed under the \"Steps\" menu. The first step is the greeting. The greeting explains how what you will need to do to make the picture. The greeting is followed by one or more MGED-based pages. These pages allow you to select geometry, view parameters, and options such as background color. Note that each of the MGED page entries has a box next to it. This box will turn green when that page has been configured. A picture can not be produced until all boxes are green. The final entry is the framebuffer configuration page. The framebuffer page is used to specify the framebuffer device, either screen or file, and the framebuffer size.\n\n" \
	    NormalTag

	$t insert insert \
	    "The RtWizard uses embedded MGED objects to allow the user to interact with the BRL-CAD database. These objects are placed are placed on a series of pages. These pages are the Full Color, Line Drawing, Highlighted Image and Ghost Image pages. The purpose of these pages is to select the objects that a rendered in the various modes. For example, the objects selected on the line-drawing page will be rendered as line drawings.\n\n" \
	    NormalTag

	$t insert insert \
	    "The MGED pages that you see depends on the type of picture that the user wishes to create. For example, if you wish to generate a simple line drawing, only the Line Drawing page is activated. However, if you wish to create a ghost image with full-color insert and lines, the ghost, full-color, and line drawing pages will be active.\n\n" \
	    NormalTag

	$t insert insert \
	    "The MGED pages are also used to specify the view parameters, that is, the orientation and size that is used for the image. If multiple MGED pages are active, only one can be used to specify the view parameters. To select a page to define the view parameters, click the \"Use this view for image\" button.\n\n" \
	    NormalTag

	$t insert insert \
	    "Common behaviors for the MGED pages:\n" \
	    Level2Tag

	$t insert insert \
	    "Use the hierarchy widget on the left to navigate the .g file. Click on an item to select it. Selected items will be shown in the small MGED window to the right. Click on an item again to deselect it. Pressing the \"Clear\" button will clear (zap) the screen. Pressing the \"Refresh\" but will redraw everything currently selected and perform autosizing.\n\n" \
	    NormalTag

	$t insert insert \
	    "Use MGED shift-grips, or the View menu, to change the view orientation and size. The View menu contains controls for the azimuth, elevation, and view size. It also includes a control for the perspective angle. Using perspective can be confusing, please be patient.\n\n" \
	    NormalTag

	$t insert insert \
	    "Full-Color page specific behaviors:\n" \
	    Level2Tag

	$t insert insert \
	    "The background color may be changed using the Options:Background Color menu.\n\n" \
	    NormalTag

	$t insert insert \
	    "Line Drawing page specific behaviors:\n" \
	    Level2Tag

	$t insert insert \
	    "The line color may be selected using the Options:Line Color control. You may also elect to use the individual region colors by selecting the Options:Use Region Colors option. The non-line color background color may be changed using the Options:Non-Line Color control. For renderings that include full-color objects, the occlusion mode may be selected using the Options:Occlusion Mode control.\n\n" \
	    NormalTag

	$t insert insert \
	    "Highlighted Image Page\n" \
	    Level2Tag

	$t insert insert \
	    "A highlighted image is simply a full-color image with a line drawing overlaid. The objects rendered in the line drawing are the same as those rendered in full color. The user may set the background color, using the Options:Background Color control. The may also set the line color, or elect to use region colors.\n\n" \
	    NormalTag

	$t insert insert \
	    "Rendering\n\n" \
	    Level1Tag

	$t insert insert \
	    "When all of the MGED pages have been configured, the Render menu becomes active. The Render menu contains two entries, preview and full-size. Selecting full-size will generate an image of the size specified on the framebuffer page to the specified framebuffer device. Selecting preview will generate a one-quarter size image to the screen. For example, a 1024x1024 image will preview at 512x512.\n\nNote that line drawings are always one pixel wide, thus the smaller the image, the more dominant the lines appear.\n\n" \
	    NormalTag


	$t tag configure Level1Tag -font {helvetica 12 bold}
	$t tag configure Level2Tag -font {helvetica 10 bold}
	$t tag configure NormalTag -font {helvetica 10}

	$t configure -state disabled
    }
}
#end namespace


# Local Variables:
# mode: Tcl
# tab-width: 8
# c-basic-offset: 4
# tcl-indent-level: 4
# indent-tabs-mode: t
# End:
# ex: shiftwidth=4 tabstop=8