chartpie — u_pbt_chartpie #

← Referência dos componentes · Índice do guia

Gráfico circular: tarte, anel ou meia roda. Cada ângulo é uma parte do todo — a legenda esconde uma fatia, as outras ocupam o seu lugar.

▶ Ver ao vivo — Aplicação de demonstração, mosaico Pie chart : a pré-visualização, o código que o produz e esta página, lado a lado.

Em resumo #

Arranque rápido #

// One slice per region : a key, a label and a value
uo_pie.of_add_slice(/*key*/ "north", /*label*/ "North", /*value*/ 420)
uo_pie.of_add_slice(/*key*/ "south", /*label*/ "South", /*value*/ 310)
uo_pie.of_add_slice(/*key*/ "east", /*label*/ "East", /*value*/ 260)

// The share of each region, written on its slice
uo_pie.ib_data_labels = true
uo_pie.is_label_format = "#percent#"

Uma fatia é uma PARTE do todo #

Você dá valores, nunca ângulos: o componente soma as fatias mostradas e dá a cada uma o ângulo da sua parte dessa soma. Esconder uma fatia — com um clique na legenda, ou através de ib_visible — fecha-a no lugar: as outras repartem de novo a roda, e #percent#, id_percent e of_total() acompanham. Um valor negativo não tem ângulo: é desenhado como zero e relê-se tal como o deu.

Os ângulos contam-se em graus, 0 em cima, no sentido do desenho: ii_start_angle = -90 e ii_sweep_angle = 180 dão a metade superior de um círculo — um indicador. A roda ajusta-se ao espaço que esse ângulo ocupa: uma meia roda é desenhada duas vezes maior.

Propriedades #

Métodos #

Eventos #

Propriedades de item #

Lidas e escritas no handle de uma fatia: uo_pie.of_item(/*key*/ "north").id_value = 450. Cada leitura pergunta ao gráfico.

Exemplos #

Um anel e o seu total #

// A hole of 60 % of the radius : a doughnut
uo_pie.id_inner_radius = 0.6

// In the hole : the slice under the pointer, in bold above its name ;
// at rest, the total of the slices shown above the word Total
uo_pie.is_center_text = "[b]#hover_value#[/b][br]#hover_label#"

// Whole numbers with a thousands separator : a display format, as in a DataWindow
uo_pie.is_format = "#,##0"

Uma meia roda como indicador #

// From the left, over half a circle : the upper half
uo_pie.ii_start_angle = -90
uo_pie.ii_sweep_angle = 180
uo_pie.id_inner_radius = 0.62

// What is spent and what is left, in the colour they mean
uo_pie.of_add_slice(/*key*/ "spent", /*label*/ "Spent", /*value*/ 72, /*color*/ RGB(/*red*/ 15, /*green*/ 108, /*blue*/ 189))
uo_pie.of_add_slice(/*key*/ "left", /*label*/ "Remaining", /*value*/ 28, /*color*/ RGB(/*red*/ 150, /*green*/ 150, /*blue*/ 150))

// The share spent, in the hole : worked out by the chart, it follows every new value
uo_pie.is_center_text = "[b]#percent:spent#[/b][br]spent"

Um painel vivo #

// Timer event of the window : new values for the same slices
// Local variables
string ls_keys[] = {"s1", "s2", "s3"}
double ld_load[]

// Read the figures, then hand them to the slices already on the chart : they
// SLIDE to their new angles instead of replaying their arrival
ld_load = wf_read_load()
uo_pie.of_set_values(/*keys*/ ls_keys, /*values*/ ld_load)

Abrir as linhas por trás de uma fatia #

// Event ue_slice_dblclicked of uo_pie : the key of the slice is the region
wf_open_orders(/*region*/ as_key, /*amount*/ ad_value)

Um menu numa fatia #

// Event ue_slice_rclicked of uo_pie : (string as_key, long al_x, long al_y)
// Remember the slice, then open the contextmenu of the window where the gesture
// was made : the pointer, or the middle of the slice for the Menu key
is_menu_slice = as_key
uo_menu.of_show(/*x*/ al_x, /*y*/ al_y)

A partir de um DataStore #

// Local variables
long ll_rc

// One slice per category : the rows of a category are SUMMED into its slice
uo_pie.of_map(/*role*/ u_pbt_chartpie.ROLE_KEY, /*column*/ "category")
uo_pie.of_map(/*role*/ u_pbt_chartpie.ROLE_LABEL, /*column*/ "category")
uo_pie.of_map(/*role*/ u_pbt_chartpie.ROLE_VALUE, /*column*/ "amount")

// ONE call reads every row of the DataStore retrieved when the window opened
// (an instance variable), no loop
ll_rc = uo_pie.of_from_datastore(/*ads*/ ids_sales)

// A row with no category is skipped : the chart says how many
if uo_pie.of_get_last_error() <> "" then wf_status(uo_pie.of_get_last_error())

A DataWindow no ecrã, relida no lugar #

// Open event of the window : the chart reads the DataWindow the user sees
uo_pie.of_map(/*role*/ u_pbt_chartpie.ROLE_KEY, /*column*/ "region")
uo_pie.of_map(/*role*/ u_pbt_chartpie.ROLE_VALUE, /*column*/ "amount")
uo_pie.of_from_datastore(/*adw*/ dw_sales)

// After a Retrieve : the slices follow IN PLACE - a region the user hid from
// the legend stays hidden, a new region gets its slice
dw_sales.Retrieve()
uo_pie.of_reload()

As fatias pequenas em «Outros» #

// Every slice under 5 % of the total joins ONE slice, drawn last in grey,
// and only the six largest products keep a slice of their own
uo_pie.id_others_threshold = 5
uo_pie.ii_others_top = 6
uo_pie.is_others_label = "Other products"

// The largest first : the reader compares them from the top
uo_pie.is_sort = u_pbt_chartpie.SORT_DESC

// Event ue_slice_clicked of uo_pie : a click on Others opens the slices it holds
// Local variables
string ls_keys[]

// Others names the slices it gathered
if as_key = uo_pie.OTHERS_KEY then
	uo_pie.of_others_keys(/*keys*/ ls_keys)
	wf_open_products(/*keys*/ ls_keys)
end if

Boas práticas #

• Poucas fatias. Para lá de seis ou sete, o olho já não compara ângulos vizinhos: agrupe as pequenas numa fatia «Outros» (id_others_threshold), ou passe ao gráfico cartesiano.
• Ordene as fatias da maior para a menor (is_sort = SORT_DESC), começando em cima: a leitura segue o sentido do desenho.
• Etiquetas fora quando as fatias são estreitas: continuam legíveis, ligadas à sua fatia, em vez de omitidas.
• Corte a animação num painel que se atualiza, ou mantenha-a e chame of_set_values: as fatias deslizam em vez de recomeçar a chegada.
• O gráfico mantém o sentido do desenho numa aplicação da direita para a esquerda — as etiquetas exteriores também se escrevem da esquerda para a direita, longe da roda; só a legenda START/END e as suas setas seguem o sentido de leitura.
• Uma imagem do gráfico (of_save_as_png, a impressão) é tirada depois de o deslizamento pousar: não é preciso cortar antes a animação.
• Uma cor que significa algo (atrasado, gasto) define-se com il_color; deixe o resto à paleta, que muda com o tema claro ou escuro.

Herdado da base comum #

Estes membros existem em todos os componentes visuais — não são próprios deste. São detalhados uma só vez, nos capítulos transversais; esta tabela apenas diz onde os ler.

Duas ajudas não são herdadas: of_icon e of_escape_markup vivem em n_pbt_utils. Declare um — n_pbt_utils lnv_utils, nada a criar — e chame-as nele.

← Referência dos componentes · Índice do guia