/ 
App-SeismicUnixGui-0.87.2
River stage zero No dependents
/ App::SeismicUnixGui::misc::blue_flow

DOCUMENTATION

SYNOPSIS

PERL PACKAGE NAME: blue_flow.pm
AUTHOR: 	Juan Lorenzo
DATE: 		June 8 2018 

DESCRIPTION 
    

BASED ON:
previous versions of the main userBuiltFlow.pl

USE

NOTES

 Provides in-house macros/superflows
 1. Find widget you have selected

if widget_name= frame then we have flow
            $var->{_flow}
            
if widget_name= menubutton we have superflow 
            $var->{_tool}

 2. Set the new program name 

   3. Make widget states active for:
     run_button
     save_button

   4. Disable the following widgets:
     delete_from_flow_button
    (sunix) flow_listbox

  sunix_listbox   		-choice of listed sunix modules in a listbox
  gui_history records updates to GUI selections
  but color_flow_href points to the changed has reference and senses
  the change as well.

Examples

SEISMIC UNIX NOTES

CHANGES and their DATES refactoring of 2017 version of L_SU.pl V 0.0.2 removed unused methods in comments

V 0.0.3 2021 allows for better color listbox control

V 0.0.4 7.10.21 allows control to handle non-numeric
names for input files

Notes

sub sunix_select (subroutine is only active in neutral_flow.pm)

Instantiation

share the following parameters in same name 
space

memory leak saviors

private anonymous hash to share variable values easily

sub _add2flow

When automatically reading a user-built perl flow and not directed to do so by a user's click of the mouse. As when a file is opened Incorporate new program parameter values and labels into the gui and save the values, labels and checkbuttons setting in the param_flow namespace

foreach my $key (sort keys %$color_flow_href) { print (" color_flow _add2flow,key is $key, value is $color_flow_href->{$key}\n"); }

_flow_select is run from _perl_flow

sub _clear_color_flow

wipe out color-flow list box with programs
wipe out param_widgets_color
wipe out parameters stored for color flow

sub _FileDialog_button

Only cases with MB binding use this private ('_') subroutine e.g., sunix programs displayed in the parameter boxes during flow construction. sub binding is responsible Other cases that select the GUI file buttons directly (user click) use: FileDialog_button instead. Once the file name is selected the parameter value is updated in the GUI

	 	 foreach my $key (sort keys %$color_flow) {
   			print (" color_flowkey is $key, value is $color_flow->{$key}\n");
  		}
  	print ("color_flow,_FileDialog_button(binding), _is_flow_listbox_color_w: $color_flow_href->{_is_flow_listbox_color_w} \n");

sub _clear_items_version_aref

clear items_versions_aref
used when last item is removed from the listbox

sub _clear_stack_versions

clear items_versions_aref
when last flow item is deleted
in the listbox

sub _flow_select_director

Private alias for flow_select both color and button are set as per the flow_select called by an active click from Main, in_L_SU_flow_bindings

sub flow_select2save_most_recent_param_flow

select a program from the flow
when add2flow_button is directly selected by the user

archive the index
and update any changed parameter flows
consider prior flow-color changes
unticked strings from GUI are corrected here
uses _updateNsave_most_recent_param_flow();

sub _flow_select2save_most_recent_param_flow

select a program from the flow
archive the index
and update any changed parameter flows

sub _get_flow_color

	get a private hash value

sub _get_flow_listbox_color_w

sub _move_in_stored_flows

move program names,
parameter names, values and checkbutton setttings
--- these are stored separately (via param_flows.pm)
from GUI widgets (via flow_widgets.pm)
The flow-widgets is a single copy of names and values
that constantly changes as the uses interacts with the GUI
The param-flows stores several program (items) and their
names and values

sub _SaveAs_button

topic: only for 'SaveAs' for safety, place set_hash_ref first

CASE #1 considered: Flow_selection is forced during _add2flow

CASE #2 if the previous items have not been directly selected with sub flow_select they will not have been updated since loading into the GUI if user made changes to the paramters but the flow was not selected via flow_select (directly by the user) the flow parameters are not correct

sub _perl_flow_errors Based on _perl_flow Parse (while reading) perl flows

sub _perl_flow Parse (while reading) perl flows

 foreach my $key (sort keys %$color_flow_href) {
  print (" color_flowkey is $key, value is $color_flow_href->{$key}\n");
 }   
  		my $length = scalar @{$all_values_aref};
  		print("color_flow,perl_flow, length = $length\n");
  		
  		for (my $j=0; $j <$length; $j++) {
  			   	print("color_flow,perl_flow,name & value:@{$all_names_aref}[$j] = @{$all_values_aref}[$j]\n");

  		}

sub _set_flow_color

sub _local_set_flow_listbox_color_w

sub _set_flow_name_color_w

sub _set_flowNsuperflow_name_w

displays superflow name at top of gui

sub _set_user_built_flow_name_w

place and show the user-built flow name

sub _stack_flow

 store an initial version of the parameters in a 
 namespace different to the one belonging to param_widgets 
 
 The initial version comes from default parameter files
 i.e., the same code as for sunix_select
 
 print("color_flow,_stack_flow, color_flow_href->{_values_aref} =@{$color_flow_href->{_values_aref}} \n");

sub _stack_versions

Collect and store latest program versions from changed list 

Will update listbox variables inside flow_widgets.pm
Therefore pop is not needed on the array
Use after data have been stored, deleted, or 
suffered an insertion event

_updateNsave_most_recent_param_flow

update parameter values of the most recently touched program in the flow

print(
	"1. START color_flow, _updateNsave_most_recent_param_flow, prior_flow_index=$prior, most_recent=$most_recent\n"
);
print(
"color_flow, START _updateNsave_most_recent_param_flow, view param flow stored data:\n"
);

hash remains partially undefined in gui_history.pm

The following two values = -1 (default) until a
second program is placed in the flow

_update_prior_param_flow

	Updates the values for parameters stored via param_flow
	param-flow takes uses parameters from param_widgets
	BUT param_widgets needs to have been updated by _update_most_recent_flow? or 
	user changes on the screen will not have been updated

	Apply every time that a flow item is selected 
	1. Assume that selection of a flow item implies pre-existing parameter values were changed/added
	
	2. Opening a file dialog assumes parameter values were also changed (Entry widget) 
	-- this means that a prior program must have been touched and that the color must change 
	from either neutral to the current color or be overwritten by the same color
		 
	Exceptions include the 
	(1) case when you have just left a flow of a different color 
	and are returning to previous settings.
	(2) case when you are using the first item in a flow for the first time, i.e. it has never been
	used before
	
	Find out the previous color, then ... there are
	2 possible CASES
		 CASE 1
		 The current color is the same as the previously touched color
		 i.e., if the last color-flow box touched was of the current flow color
		 i.e., consider situation when we are still using the same colored list box
		 
		 in which case...		
		 1. Find out which index was touched in "color"-flow box
		 2. Find out which program was previously touched
		 3. Assume the touched program had its parameter values modified
		 4. Update all the previously touched program's values in storage via param_flow
		 
		 CASE 2
		 If the current color is different to the previously touched color, then 		
		 2. ELIMINATE all the previous changes
  		 
  	Clicking Save will activate _update_prior_param_flow.  
  			Before Save is clicked:
  			 the 
  			_last_parameter_index_touched_color = 0
         	_last_flow_index_touched 			= -1
         	_last_flow_color 					= current flow color
 
 
			 print("1. color_flow, _update_prior_param_flow, start\n");
			$param_flow_color_pkg->view_data();

			# print("2. color_flow, _update_prior_param_flow, print gui_history.txt\n");
			# $gui_history->view();
			
					 deprecated 1.23.23
				if (   $prior_flow_color eq $neutral
				       or $prior_flow_color eq $most_recent_flow_color )

  
  
		print(
"color_flow,_update_prior_param_flow,prior_color_flow = $prior_flow_color\n"
		);
		print("2 color_flow, _update_prior_param_flow, start\n");
		$param_flow_color_pkg->view_data();

		print(
"3. color_flow,_update_prior_param_flow,names, color_flow: @{$color_flow_href->{_names_aref}}\n"
		);
		print(
"3.color_flow,_update_prior_param_flow,values, color_flow: @{$color_flow_href->{_values_aref}}\n"
		);
		print(
"3.color_flow,_update_prior_param_flow,n, param_widgets:@{$param_widgets->get_labels_aref()}\n"
		);
		print(
"3.color_flow,_update_prior_param_flow,values, param_widgets:@{$param_widgets->get_values_aref()}\n"
		);
			print("1. color_flow,_update_prior_param_flow, prior_flow and storage index=$storage_flow_index\n");
	print("color_flow,_update_prior_param_flow,most_recent_flow_index=$most_recent_flow_index_touched\n");
		
   		print("4.color flow,_update_prior_param_flow \n");
		$param_flow_color_pkg->view_data();

_save_most_recent_param_flow

	Force to save flow parameters to param_flow
	 
	We assume that the program of interest within an active flow stays the same.
	Nevertheless that a parameter within a fixed program has changed so that
	the stored parameters for that program need to be updated. (TODO??)
	That is, param_flow will update the stored parameters for a member of the flow
	without having to change the flow item/program with which we interact.
	
	The checkbuttons, values and names of only the present program in use 
  	are stored in param_widgets at any one time
  	
  	After selecting  a data file name, the file name is automatically inserted
  	into the GUI. Following, we update the data file name into the stored parameters via param_flow
  	
	$last_parameter_index_touched_color must =0 or > 0
	but does exist and means the parameters are untouched

sub FileDialog_button

Handles Data, SaveAs and (perl) Open (in) or Delete May provide values from the current widget if it is used. Can also be (1) a previous pre-built superflow that is already in the GUI or 2) empty if program is just starting

 dialog type (option_sref)  can be:
  	Data, 
  	Open (open an exisiting user-built flow, but not a pre-built
  				superflow), or
  	SaveAs
  	
  	Delete ( a file or any type, default $PL_SEISMIC)
  			
  	my $uBF      	= $file_dialog->get_hash_ref(); 
		foreach my $key (sort keys %$uBF) {
   			print (" color_flowkey is $key, value is $uBF->{$key}\n");
  		}

sub add2flow_button

	When build a first-time perl flow
	Incorporate new prorgam parameter values and labels into the gui
	and save the values, labels and checkbuttons setting in the param_flow
	namespace

  		foreach my $key (sort keys %$color_flow_href) {
   			print (" color_flow key is $key, value is $color_flow_href->{$key}\n");
  		}
  		
	$ans= $color_flow_href->{_param_sunix_length};
	print("1b. color_flow, add2flow_button, _param_sunix_length= $ans\n");

sub delete_from_flow_button

if flow_select was last clicked then $gui_history has already recorded the chosen flow color

my $flow_color = $gui_history->get_flow_color();

sub delete_whole_flow_button

If flow_select was last clicked then $gui_history has already recorded the chosen flow color

sub flow_item_down_arrow_button

	move items down in a flow listbox

sub flow_item_up_arrow_button

		move items up in a flow listbox

sub flow_select

Pick a Seismic Unix module from within a (colored) flow listbox

Always takes focus on first entry ; index = 0 If focus is on first entry then also make the $color_flow_href->{_last_parameter_index_touched_color} =0

print(" flow_select, view stored param flow data before update of prior\n"); $param_flow_color_pkg->view_data(); my $ans = @{$color_flow_href->{_values_w_aref}}[0]->get;

print("color_flow,flow_select, print gui_history\n"); $gui_history->view();

 print("12color_flow, flow_select, extract saved values\n");
 $param_flow_color_pkg->view_data();
 
 								print(
"1 color_flow, flow_select, num_items_in_flow =$num_items_in_flow\n"
					);
					print(
"1 color_flow, flow_select, max_index_in_flow =$max_index_in_flow\n"
					);
					print(
"1 color_flow, flow_select, most_recent_flow_index =$most_recent_flow_index\n"
					);
					print(
"1 color_flow, flow_select, last_flow_color=$last_flow_color\n");

 								print(
"2 color_flow, flow_select, num_items_in_flow =$num_items_in_flow\n"
					);
					print(
"2 color_flow, flow_select, max_index_in_flow =$max_index_in_flow\n"
					);
					print(
"2 color_flow, flow_select, most_recent_flow_index =$most_recent_flow_index\n"
					);

sub get_Flow_file_exists

sub get_hash_ref exports private hash 46

sub get_flow_color exports private hash value

sub get_flow_type

	exports private hash value

sub get_perl_flow_errors

sub get_prog_name_sref

	exports private hash value

sub increase_vigil_on_delete_counter

	Helps keep check of whether an item
    is deleted from the listbox
    during dragging and dropping

sub get_help

Callback sequence following MB3 click 
activation of a sunix (Listbox) item
program name is a scalar reference

Let help decide whether it is a superflow
or a user-created flow

Show a window with the perldoc to the user

and length $color_flow_href->{_sunix_prog_group}

sub save_button

	topic: only 'Save'
  	for safety, place set_hash_ref first
  	run from L_SU.pm
  	
  	Also save new parameter values (redisplay_values)
  	for changes occurred
  	immediately before the current saving 
  	
  	param_flow_color memory leak workaround
  	
  			#		print("color_flow, save_button writing gui_history.txt\n");
		#		$gui_history->view();

		#		print("3. color_flow, save_button, param_flow view data\n"
		#				);
		#				$param_flow_color_pkg->view_data();
		
					  				print(
"5. color_flow, save_button, memory fix, click count=$click_count\n"
				); # =7 < 19 default  OK
							  				print(
"5. color_flow, save_button, most_recent_flow_index_touched=$last_flow_index\n"
				); #=2 OK
							  				print(
"5. color_flow, save_button, max_saved_widget_index=$max_saved_widget_index\n"
				);				# =1 TODO
print("5 color_flow,save_last_param_widget_values=@save_last_param_widget_values\n");

# print("5. color_flow, save_button, Can not fix memory leak\n"); # print( print( "5. color_flow, save_button, this_color,last_flow_color are:$this_color,$last_flow_color\n" ); print( "5. color_flow, save_button, most recent flow index touched is $most_recent_flow_index_touched\n" ); print( "5. color_flow, save_button, max index in flow: $max_index_in_flow\n" );

# print( #"5. color_flow, save_button, last flow index: $last_flow_index\n" # ); # print( #"5. color_flow, save_button, max_saved_widget_index was $max_saved_widget_index\n" # ); # print( #"5. color_flow, save_button, click_count:$click_count min_clicks4save_button:$min_clicks4save_button\n" # );

CASE common : When save_button is being used for the first time BUT when no flow has been selected previously (_last_flow_index_touched=-1) In other words: when a flow in the GUI is used for first time but no listboxes have been occupied previously

sub set_hash_ref Import external hash into private settings via gui_history hash

Keys that used simplified names are also kept so later the hash can be returned to a calling module

print("color_flow, END of flow_select: writing gui_history.txt\n"); $gui_history->view();

sub set_occupied_listbox_aref

sub set_vacant_listbox_aref

1 POD Error

The following errors were encountered while parsing the POD:

Around line 1601:

=pod directives shouldn't be over one line long! Ignoring all 2 lines of content