YKLook説明書＞クラス解説＞ YKLookGraphBar

棒グラフの表示情報を保持するオブジェクトです。
単一の層の棒グラフだけでなく、複数の層からなる積み上げ棒グラフの情報も保持できます。
このオブジェクト自体には画面表示機能はありません。
実際に画面に表示するには、 YKLookCanvas#yk_draw_graph() を使います。

このクラスを使うときは、 swinggraph をロードしてください。
また、表示するためには swingcanvas もロードしてください。

例	require 'yklook/swing' require 'yklook/swingcanvas' require 'yklook/swinggraph'

注意：	このクラスは追加機能です。当社ライセンスに付属します。

インスタンスを生成します。
引数の width は整数で、このグラフで表示可能な領域全体の幅を指定します。
引数の height は整数で、このグラフで表示可能な領域全体の高さを指定します。
単位はいずれもピクセルです。

実際にグラフを描画する領域は、ここで指定した領域からマージン（余白）を差し引いたサイズになります。
領域全体を「外枠」、マージン（余白）を差し引いたサイズを「内枠」と表現します。
マージン（余白）については yk_set_margin() の説明をご覧ください。

グラフとして表示する実際の数値データとその項目名を指定します。
このメソッドひとつで、グラフの棒の１本分を表します。

引数の name は項目名を表す文字列です。
これは１本の棒に付ける名前で、この棒の下側（正確にはグラフ内枠の下側）に表示します。

引数の values はグラフ表示のもとになる実際の数値データです。
数値データは整数または実数で指定してください。
多層の積み上げ棒グラフを表示するときは、引数の values は配列です。
以下の例をご覧ください。

例１

g.yk_add_item_data( '１日',  10  )
g.yk_add_item_data( '２日',  20  )
g.yk_add_item_data( '３日',  30  )

例２

g.yk_add_item_data( '１日', [10] )
g.yk_add_item_data( '２日', [20] )
g.yk_add_item_data( '３日', [30] )

この例では、３本の棒グラフを表示します。
棒グラフが１層だけのときは、例１と例２のどちらでも受け付けます。

例３	g.yk_add_item_data( '１日', [10,40] ) g.yk_add_item_data( '２日', [20,50] ) g.yk_add_item_data( '３日', [30,60] )

この例では、３本の棒グラフを表示し、それぞれの棒は２層になります。

積み上げ棒グラフのとき、メソッド yk_set_item_attr() の指定によって積み上げる順番が変わります。
上の例でいうと、配列内の要素の順に積み上げるのがデフォルトです。
つまり、 10,20,30 の層の上に、 40,50,60 の層を積み上げます。

注意：	`yk_set_item_data()` と `yk_add_item_data()` を組み合わせて使うことはできません。 `yk_set_item_data()` を使って一度にすべての数値データを指定するか、 `yk_add_item_data()` を必要な回数だけ使って数値データを指定するか、いずれかの方法になります。このふたつのメソッドは、数値データの指定方法が異なるので、プログラム製作者の都合にあわせてどちらか使いやすい方を使ってください。

グラフの目盛りで表示する文字列を追加します。
引数の value は、実際の数値を整数または実数で指定します。
引数の char は、表示する文字列を指定します。
引数の space は、目盛りを付ける縦線（垂直線、あるいはＹ軸）との隙間を整数で指定します。単位はピクセルです。
space を省略したときの値は 5 になります。
引数の color は、文字列の色を指定します。
color の指定方法は、 YKLookColor.new() の引数と同じです。
color を省略したときの色は、黒になります。

例	g = YKLookGraphBar.new( 150, 100 ) g.yk_add_scale_char( 10000, '１万', 5, 'black' ) g.yk_add_scale_char( 20000, '２万', 5, 'black' )

この例では、実際の値が 10000 と 20000 に相当する位置にそれぞれ ' １万 ' と ' ２万 ' を表示します。目盛りの縦線（垂直線、あるいはＹ軸）から 5 ピクセル外側に表示します。

デフォルトでは、この文字列は表示しません。
プログラム製作者の必要に応じて追加してください。

表示しているグラフ内枠の背景に、水平線を表示します。
引数の value は、実際の数値を整数または実数で指定します。
引数の color は、水平線の色を指定します。
color の指定方法は、 YKLookColor.new() の引数と同じです。
color を省略したときの色は、黒になります。

例	g = YKLookGraphBar.new( 150, 100 ) g.yk_add_scale_line( 10000, 'black' ) g.yk_add_scale_line( 20000, 'black' )

この例では、実際の値が 10000 と 20000 に相当する位置にそれぞれ水平線を表示します。

デフォルトでは、この水平線は表示しません。
プログラム製作者の必要に応じて追加してください。

グラフの目盛りとなる短い横線を追加します。
引数の min は、表示する目盛りの最小値を指定します。
引数の max は、表示する目盛りの最大値を指定します。
引数の unit は、表示する目盛りの間隔を指定します。
この値が、目盛りひとつ分の増分値となります。
引数の out は、表示する目盛りの横線のうち、グラフ内枠の外側に描画する長さを指定します。
引数の in は、表示する目盛りの横線のうち、グラフ内枠の内側に描画する長さを指定します。
引数の color は、表示する目盛りの横線の色を指定します。

min , max , unit は整数または実数で指定します。
out , in は整数で、単位はピクセルです。
color の指定方法は、 YKLookColor.new() の引数と同じです。
out と in と color は省略できます。
省略時の値はそれぞれ 3 と 0 と 'black' になります。

例	g = YKLookGraphBar.new( 150, 100 ) g.yk_add_scale_mark( 500, 3000, 500, 3, 0, 'black' ) g.yk_add_scale_mark( 1000, 3000, 1000, 5, 0, 'black' )

この例では、実際の値が 500,1000,1500,2000,2500,3000 に相当する位置に目盛り線を描画します。線の幅は、グラフ内枠の外側に３ピクセルです。
そのうち 1000,2000,3000 については５ピクセルで上書きしています。

デフォルトでは、この目盛りは表示しません。
プログラム製作者の必要に応じて追加してください。

棒グラフの棒の横幅と、棒と棒の隙間を指定します。
引数の bar は棒の横幅を指定します。
引数の space は棒と棒の隙間を指定します。
いずれの引数も整数または実数です。
ここで指定する数値は相対的な割合を表すもので、ピクセルではありません。
以下の例を参考にしてください。

例１	g.yk_set_bar_width( 2 , 1 )
例２	g.yk_set_bar_width( 3 , 2 )

この例１では、棒の幅と隙間の割合が 2:1 になるように指定しています。
この例２では、棒の幅と隙間の割合が 3:2 になるように指定しています。

デフォルトの値は、棒と隙間の割合が 2:1 になります。

積み上げ棒グラフのときの、各層と数値データと表示色の対応を指定します。
引数の data は文字列で、 yk_set_item_data() や yk_add_item_data() で指定する数値データの積み上げ順を表します。
以下の中から指定してください。

指定	意味
`'normal'`	指定された数値データの順番どおりに積み上げていきます。
`'reverse'`	最後に指定した数値データから順に積み上げていきます。

英字の大文字小文字はどちらでも受け付けます。
また、 YKLook 内部では先頭の１文字だけを見ています。
デフォルトは 'n' です。

引数の color も同様です。
こちらは yk_set_item_color() で指定する色の積み上げ順を表します。

指定	意味
`'normal'`	指定された色の順番どおりに積み上げていきます。
`'reverse'`	最後に指定した色から順に積み上げていきます。

英字の大文字小文字はどちらでも受け付けます。
また、 YKLook 内部では先頭の１文字だけを見ています。
デフォルトは 'n' です。

棒グラフの各部位の色を指定します。
いずれも色の指定方法は、 YKLookColor.new() の引数と同じです。

引数の name は項目名（棒の名前）の色を指定します。
項目名は、それぞれの棒の下側（正確にはグラフ内枠の下側）に横並びで表示することになります。

引数の values は棒の色を指定します。
詳細は後述の例とともに説明します。

引数の border は棒の枠線（縁取り）の色を指定します。
border は引数自体を省略可能で、そのときの色は黒になります。
枠線（縁取り）を描かないときは、 nil を指定してください。

values は、色を要素とする配列の形で指定することもできます。
多層の積み上げ棒グラフを表示するときは、引数の values は常に配列で指定してください。
以下の例をご覧ください。

例１	g.yk_set_item_color( 'black', 'grey', 'black' )
例２	g.yk_set_item_color( 'black', ['blue','red'] )

前者は、層がひとつだけの棒グラフの指定例です。
後者は、２層の積み上げ棒グラフの指定例です。
この例２では、 border の指定を省略しています。

積み上げ棒グラフのとき、メソッド yk_set_item_attr() の指定によって積み上げる順番が変わります。
上の例２でいうと、配列内の要素の順に積み上げるのがデフォルトです。
つまり、 'blue' の層の上に、 'red' の層を積み上げます。

層の数と、 values の数が合わないときは、以下のようになります。

層の数のほうが少ないときは、その数だけ values 内の色を使います。
層の数のほうが多いときは、 values 内の色を順に繰り返し使います。

例えば、 values が赤青緑の３色指定しているとき、１層なら赤になり、５層なら赤青緑赤青になります。このとき yk_set_item_attr() の指定によっては、１層なら緑になり、５層なら緑青赤緑青になります。

層の数がひとつであるにも関わらず、 values の数が複数指定（プログラム製作者による明示的な指定）されたとき、 values の数と表示するグラフの棒の数とが等しい場合は、それぞれの棒の色として扱います。

このメソッドのデフォルト値は以下のとおりです。

引数	値
`name`	`'black'` （黒）
`values`	`['#ffccff','#ffcccc','#ccffcc']` （桃色、薄紅、薄緑）
`border`	`'black'` （黒）

グラフとして表示する実際の数値データとその項目名を指定します。
引数の names は配列で、その要素は項目名を表す文字列です。
この配列の要素の数は、グラフに表示する棒の数と同じになります。
ようするに項目名は、それぞれの棒に付ける名前になり、グラフ内枠の下側に横並びで表示することになります。
引数の values は配列で、グラフ表示のもとになる実際の数値データです。
数値データは整数または実数で指定してください。
多層の積み上げ棒グラフを表示するときは、引数の values は二重の配列になります。以下の例をご覧ください。

例

bar_name = [ '１日', '２日', '３日' ] # 三日間の販売数
product  = [ 10, 20, 30 ]     # 製品の三日間の販売数
g.yk_set_item_data( bar_name,  product  )  # 例１
g.yk_set_item_data( bar_name, [product] )  # 例２

この例では、３本の棒グラフを表示します。
この棒グラフは１層だけなので、例１と例２のどちらでも受け付けます。

例

bar_name  = [ '１日', '２日', '３日' ] # 三日間の販売数
product_a = [ 10, 20, 30 ]     # 製品Ａの三日間の販売数
product_b = [ 40, 50, 60 ]     # 製品Ｂの三日間の販売数
g.yk_set_item_data( bar_name, [product_a, product_b] )

この例では、３本の棒グラフを表示し、それぞれの棒は２層になります。

積み上げ棒グラフのとき、メソッド yk_set_item_attr() の指定によって積み上げる順番が変わります。
上の例でいうと、製品Ａの上に製品Ｂを積み上げるのがデフォルトです。

注意：	`yk_set_item_data()` と `yk_add_item_data()` を組み合わせて使うことはできません。 `yk_set_item_data()` を使って一度にすべての数値データを指定するか、 `yk_add_item_data()` を必要な回数だけ使って数値データを指定するか、いずれかの方法になります。このふたつのメソッドは、数値データの指定方法が異なるので、プログラム製作者の都合にあわせてどちらか使いやすい方を使ってください。

それぞれの棒の下側（正確にはグラフ内枠の下側）に表示する項目名（棒の名前）のフォントを指定します。
引数の font は、 nil または YKLookFont クラスのオブジェクトです。
nil のときは、デフォルト値になります。
デフォルトのフォントはＯＳごとに異なりますが、いずれの場合もデフォルトのフォントサイズは 12 ポイントになります。

引数の space は整数で、グラフ内枠と名前の隙間を指定します。
単位はピクセルで、省略時のデフォルトは 2 になります。

グラフ表示時のマージン（余白）を指定します。
実際のグラフ本体の描画範囲は、 new() で指定した表示幅と表示高さから、この余白を除いたサイズになります。
new() で指定した領域全体を「外枠」、マージン（余白）を除いたサイズを「内枠」と表現します。

引数の top は、グラフ内枠の上側の余白を指定します。
引数の bottom は、グラフ内枠の下側の余白を指定します。
引数の left は、グラフ内枠の左側の余白を指定します。
引数の right は、グラフ内枠の右側の余白を指定します。
いずれの引数も整数で、単位はピクセルです。
デフォルトの値は、それぞれ 5, 15, 20, 5 になります。

左側または右側の余白部分に、グラフの目盛りを表示します。
下側の余白部分に、項目名を表示します。
項目名とは、棒グラフとして表示するそれぞれの棒に付ける名前であり、グラフ内枠の下側の余白部分に横並びで表示することになります。

グラフ表示時の隙間を指定します。
グラフ内枠のさらに内側に、ここで指定した値のぶんだけ隙間を入れます。
引数の top は、グラフ内枠の上端の隙間を指定します。
引数の bottom は、グラフ内枠の下端の隙間を指定します。
引数の left は、グラフ内枠の左端の隙間を指定します。
引数の right は、グラフ内枠の右端の隙間を指定します。
いずれの引数も整数で、単位はピクセルです。

この隙間のデフォルト値は、実際に表示するグラフの棒の本数や数値データの内容により自動的に調整した値となります。

グラフの目盛り全体についての設定です。
引数の min は、このグラフで表示可能な最小値を指定します。
この値は、実際にグラフとして表示する数値の中で最も小さい値と同じ値にするか、またはその値よりも小さい値を指定します。
整数または実数で指定してください。
min は、グラフ内枠の下端（隙間があるときは、その位置）が示す数値として扱います。
数値の代わりに nil を指定すると、実際の数値データの中の最小値を意味します。
デフォルトは nil です。

引数の max は、このグラフで表示可能な最大値を指定します。
この値は、実際にグラフとして表示する数値の中で最も大きい値と同じ値にするか、またはその値よりも大きい値を指定します。
整数または実数で指定してください。
max は、グラフ内枠の上端（隙間があるときは、その位置）が示す数値として扱います。
数値の代わりに nil を指定すると、実際の数値データの中の最大値を意味します。
デフォルトは nil です。

引数の side は、グラフの目盛りの表示位置を指定します。
グラフ内枠の左右のどちら側に配置するかを指定します。
以下の中から指定してください。

指定	意味
`'LEFT'`	グラフ内枠の左側
`'RIGHT'`	グラフ内枠の右側
`'NONE'`	目盛りを付けない

英字の大文字小文字はどちらでも受け付けます。
また、 YKLook 内部では先頭の１文字だけを見ています。
デフォルトは 'L' です。

引数の color は目盛りを付けるときの縦線（垂直線、あるいはＹ軸）の色を指定します。
デフォルトは黒です。
この縦線は、グラフ内枠の左側または右側に描画します。
color の指定方法は、 YKLookColor.new() の引数と同じです。

例	g = YKLookGraphBar.new( 150, 100 ) g.yk_set_scale_attr( 0, 3000, 'L', 'black' )

引数の side と color は省略できます。
省略時の値はデフォルトと同じになります。

数値データの値をもとに、目盛りの大きさを自動的に調節して表示します。
目盛りの横に表示する文字列も自動的に付けます。
すべての引数にはデフォルト値が設定してあるので、引数を省略できます。

引数の mark_out , mark_in , mark_color は、目盛りに付ける短い横線だけを表示するときの設定です。
引数の both_out , both_in , both_color は、目盛りだけでなく、その位置に文字列も表示するときの目盛りの横線についての設定です。
引数の char_space , char_color は、文字列についての設定です。

例えば、実際の数値データの最大値が６のときは以下のようになります。

数値の６、４、２、０の位置には目盛りと文字列「６」「４」「２」「０」を表示。
このとき both_out , both_in , both_color , char_space , char_color の設定に従って表示する。
数値の５、３、１の位置には目盛りのみ表示。
このとき mark_out , mark_in , mark_color の設定に従って表示する。

それぞれの引数の意味は、 yk_add_scale_mark() と yk_add_scale_char() をご覧ください。

引数の figure_number と figure_name は、表示する数値の桁数が大きいときの表示方法の設定です。
figure_number で桁数の単位を指定し、 figure_name でその桁ごとの名前を指定します。
figure_name は配列で、その要素は文字列です。

例１

f = [ '万', '億', '兆', '京', '垓' ]
g.yk_set_scale_auto( 4, 0, nil, 2, 0, nil, 3, nil, 4, f )

例２

f = [ 'k', 'M', 'G', 'T', 'P', 'E', 'Z', 'Y' ]
g.yk_set_scale_auto( 4, 0, nil, 2, 0, nil, 3, nil, 3, f )

それぞれの引数のデフォルト値は以下のとおりです。

引数	値
`mark_out`	`4`
`mark_in`	`0`
`mark_color`	黒。 `nil` を指定したときも黒になる。
`both_out`	`2`
`both_in`	`0`
`both_color`	黒。 `nil` を指定したときも黒になる。
`char_space`	`3`
`char_color`	黒。 `nil` を指定したときも黒になる。
`figure_number`	`4`
`figure_name`	`figure_number` の値が `4` のときは `[ '` 万 `', '` 億 `', '` 兆 `', '` 京 `', '` 垓 `' ]` 。 `figure_number` の値が `3` のときは `[ 'k', 'M', 'G', 'T', 'P', 'E', 'Z', 'Y' ]` どちらでもないときは、 `figure_number` の値を強制的に `4` とみなす。

注意：	グラフの数値データの最大値が `1` 未満 `0` 以上のときは、桁数の単位や名前の指定ができませんので、単純に `0.00001` のような表示になります。グラフの数値データの最大値がマイナスのときは、このメソッドは何もしません。