~cfuhrman/+junk/netbsd-othersrc-trunk

CDKSCROLL *newCDKScroll (CDKSCREEN *\f2screen\f1, int \f2xpos\f1, int \f2ypos\f1, int \f2spos\f1, int \f2height\f1, int \f2width\f1, char *\f2title\f1, char **\f2scrollList\f1, int \f2scrollListLength\f1, boolean \f2numbers\f1, chtype \f2highlight\f1, boolean \f2box\f1, boolean \f2shadow\f1);

138

.RS 3

139

This function creates a pointer to a scroll widget. The \f2screen\f1 parameter

140

is the screen you wish this widget to be placed in. The parameter \f2xpos\f1

141

controls the placement of the object along the horizontal axis. This parameter

142

can accept an integer value or one of the pre-defined values of \f4LEFT\f1,

143

\f4RIGHT\f1, and \f4CENTER\f1. The parameter \f2ypos\f1 controls the placement

144

of the object along the vertical axis. This parameter can accept an integer

145

value or one of the pre-defined values of \f4TOP\f1, \f4BOTTOM\f1, and \f4CENTER\f1.

146

The parameter \f2spos\f1 is where the scroll bar is to be placed. This can

147

accept one of three values: \f4LEFT\f1, which puts the scroll bar on the left

148

of the scrolling list. \f4RIGHT\f1 which puts the scroll bar on the right side

149

of the list, and \f4NONE\f1 which does not add a scroll bar. The parameters

150

\f2height\f1 and \f2width\f1 control the height and width of the widget. If

151

you provide a value of zero for either of the height or the width, the widget will

152

be created with the full width and height of the screen. If you provide a negative

153

value, the widget will be created the full height or width minus the value provided.

154

The \f2title\f1 parameter is the string which will be displayed

155

at the top of the widget. The title can be more than one line; just provide a

156

carriage return character at the line break. The parameter \f2scrollList\f1 is

157

the list of items to be displayed in the scrolling list; \f2scrollListLength\f1

158

is the number of elements in the given list. The parameter \f2numbers\f1 is a

159

boolean value stating that you want the items in the list to have a number

160

attached to the front of the list items. The \f2highlight\f1 parameter specifies

161

the display attribute of the currently selected item. The \f2box\f1 parameter

162

states whether the widget will be drawn with a box around it or not. The \f2shadow\f1

163

parameter accepts a boolean value to turn the shadow on or off around this widget.

164

If the widget could not be created then a \f4NULL\f1 pointer is returned.

165

.RE

166

167

int activateCDKScroll (CDKSCROLL *\f2scroll\f1, chtype *\f2actions\f1);

168

.RS 3

169

This function activates the scroll widget and lets the user interact with the

170

widget. The parameter \f2scroll\f1 is a pointer to a non-NULL scroll widget.

171

If the \f2actions\f1 parameter is passed with a non-NULL value, the characters

172

in the array will be injected into the widget. To activate the widget

173

interactively pass in a \f4NULL\f1 pointer for \f2actions\f1. If the character entered

174

into this widget is \f4RETURN\f1 or \f4TAB\f1 then this function will return a

175

value from 0 to the number of items-1, representing the item selected. It

176

will also set the structure member \f4exitType\f1 to \f4vNORMAL\f1. If the

177

character entered into this widget was \f4ESCAPE\f1 then the widget will return

178

a value of -1 and the structure member \f4exitType\f1 will be set to

179

\f4vESCAPE_HIT\f1.

180

.RE

181

182

int injectCDKScroll (CDKSCROLL *\f2scroll\f1, chtype \f2character\f1);

183

.RS 3

184

This function injects a single character into the widget. The parameter

185

\f2scroll\f1 is a pointer to a non-NULL scroll widget. The parameter

186

\f2character\f1 is the character to inject into the widget. If the character

187

injected into this widget was \f4RETURN\f1 then the character injected into

188

this widget is \f4RETURN\f1 or \f4TAB\f1 then this function will return a

189

value from 0 to the number of items-1, representing the item selected. It

190

will also set the structure member \f4exitType\f1 to \f4vNORMAL\f1. If the

191

character entered into this widget was \f4ESCAPE\f1 then the widget will return

192

a value of -1 and the structure member \f4exitType\f1 will be set to

193

\f4vESCAPE_HIT\f1. Any other character injected into the widget will set the

194

structure member \f4exitType\f1 to \f4vEARLY_EXIT\f1 and the function will

195

return -1.

196

.RE

197

198

void setCDKScroll (CDKSCROLL *\f2scroll\f1, char **\f2scrollList\f1, int \f2scrollListLength\f1, boolean \f2numbers\f1, chtype \f2highlight\f1, boolean \f2box\f1);

199

.RS 3

200

This function lets the programmer modify certain elements of an already defined

201

scroll widget. The parameter names correspond to the same parameter names listed

202

in the \f4newCDKScroll\f1 function.

203

.RE

204

205

void setCDKScrollItems (CDKSCROLL *\f2scroll\f1, char **\f2itemList\f1, int \f2listSize\f1, boolean \f2numbers\f1);

206

.RS 3

207

This function sets the contents of the scrolling list.

208

.RE

209

210

int getCDKScrollItems (CDKSCROLL *\f2scroll\f1, char **\f2itemList\f1);

211

.RS 3

212

This fills the parameter \f2itemList\f1 with the contents of the scrolling

213

list. It returns the number of elements in the scrolling list.

214

.RE

215

216

void setCDKScrollHighlight (CDKSCROLL *\f2scroll\f1, chtype \f2highlight\f1);

217

.RS 3

218

This sets the attribute of the highlight bar.

219

.RE

220

221

chtype getCDKScrollHighlight (CDKSCROLL *\f2scroll\f1);

222

.RS 3

223

This returns the attribute of the highlight bar.

224

.RE

225

226

void setCDKScrollBox (CDKSCROLL *\f2scroll\f1, boolean \f2boxWidget\f1);

227

.RS 3

228

This sets whether or not the widget will be draw with a box around it.

229

.RE

230

231

boolean getCDKScrollBox (CDKSCROLL *\f2scroll\f1);

232

.RS 3

233

This returns whether or not the widget will be drawn with a box around it.

234

.RE

235

236

void addCDKScrollItem (CDKSCROLL *\f2scroll\f1, char *\f2item\f1);

237

.RS 3

238

This function allows the user to add an item into an already defined scrolling

239

list. The \f2scroll\f1 parameter is a pointer to the scrolling list to add the

240

item to. The parameter \f2item\f1 is a \f4char *\f1 representing the new item

241

to add. The item is always added to the end of the list.

242

.RE

243

244

void deleteCDKScrollItem (CDKSCROLL *\f2scroll\f1, int \f2position\f1);

245

.RS 3

246

This function allows the user to add an item into an already defined scrolling

247

list. The \f2scroll\f1 parameter is a pointer to the scrolling list to add the

248

item to. The parameter \f2f2position\f1 is an \f4int\f1 which specifies which

249

element to remove.

250

.RE

251

252

void setCDKScrollULChar (CDKSCROLL *\f2scroll\f1, chtype \f2character\f1);

253

.RS 3

254

This function sets the upper left hand corner of the widgets box to

255

the given character.

256

.RE

257

258

void setCDKScrollURChar (CDKSCROLL *\f2scroll\f1, chtype \f2character\f1);

259

.RS 3

260

This function sets the upper right hand corner of the widgets box to

261

the given character.

262

.RE

263

264

void setCDKScrollLLChar (CDKSCROLL *\f2scroll\f1, chtype \f2character\f1);

265

.RS 3

266

This function sets the lower left hand corner of the widgets box to

267

the given character.

268

.RE

269

270

void setCDKScrollLRChar (CDKSCROLL *\f2scroll\f1, chtype \f2character\f1);

271

.RS 3

272

This function sets the lower right hand corner of the widgets box to

273

the given character.

274

.RE

275

276

void setCDKScrollVerticalChar (CDKSCROLL *\f2scroll\f1, chtype \f2character\f1);

277

.RS 3

278

This function sets the vertical drawing character for the box to

279

the given character.

280

.RE

281

282

void setCDKScrollHorizontalChar (CDKSCROLL *\f2scroll\f1, chtype \f2character\f1);

283

.RS 3

284

This function sets the horizontal drawing character for the box to

285

the given character.

286

.RE

287

288

void setCDKScrollBoxAttribute (CDKSCROLL *\f2scroll\f1, chtype \f2attribute\f1);

289

.RS 3

290

This function sets the attribute of the box.

291

.RE

292

293

void setCDKScrollBackgroundColor (CDKSCROLL *\f2scroll\f1, char *\f2color\f1);

294

.RS 3

295

This sets the background color of the widget. The parameter \f2color\f1

296

is in the format of the Cdk format strings. To get more information look

297

at the \f4cdk_display\f1 manual page.

298

.RE

299

300

void moveCDKScroll (CDKSCROLL *\f2scroll\f1, int \f2xpos\f1, int \f2ypos\f1, boolean \f2relative\f1, boolean \f2refresh\f1);

301

.RS 3

302

This function moves the given widget to the given position. The parameters

303

\f2xpos\f1 and \f2ypos\f1 is the new position of the widget. The parameter

304

\f2xpos\f1 can accept an integer value or one of the pre-defined values of

305

\f4TOP\f1, \f4BOTTOM\f1, and \f4CENTER\f1. The parameter \f2ypos\f1 can

306

accept an integer value or one of the pre-defined values of \f4LEFT\f1,

307

\f4RIGHT\f1, and \f4CENTER\f1. The parameter \f2relative\f1 states whether

308

the \f2xpos\f1/\f2ypos\f1 pair is a relative move or an absolute move. For

309

example if \f2xpos\f1 = 1 and \f2ypos\f1 = 2 and \f2relative\f1 = \f2TRUE\f1,

310

then the widget would move one row down and two columns right. If the value

311

of \f2relative\f1 was \f2FALSE\f1 then the widget would move to the position

312

(1,2). Do not use the values of \f4TOP\f1, \f4BOTTOM\f1, \f4LEFT\f1,

313

\f4RIGHT\f1, or \f4CENTER\f1 when \f2relative\f1 = \f4TRUE\f1. (wierd things

314

may happen). The final parameter \f2refresh\f1 is a boolean value which states

315

whether the widget will get refreshed after the move or not.

316

.RE

317

318

void positionCDKScroll (CDKSCROLL *\f2scroll\f1);

319

.RS 3

320

This function allows the user to move the widget around the screen via the

321

cursor/keypad keys. The following key bindings can be used to move the

322

widget around the screen.

323

.LP

324

.nf

325

\f4Key Bindings\f1

326

.RS 3

327

\f2Key Action\f1

328

Up Arrow Moves the widget up one line.

329

Down Arrow Moves the widget down one line.

330

Left Arrow Moves the widget left one column

331

Right Arrow Moves the widget right one column

332

Keypad-1 Moves the widget down one line

333

and left one column.

334

Keypad-2 Moves the widget down one line.

335

Keypad-3 Moves the widget down one line

336

and right one column.

337

Keypad-4 Moves the widget left one column

338

Keypad-5 Centers the widget both vertically

339

and horizontally.

340

Keypad-6 Moves the widget right one column

341

Keypad-7 Moves the widget up one line

342

and left one column.

343

Keypad-8 Moves the widget up one line.

344

Keypad-9 Moves the widget up one line

345

and right one column.

346

t Moves the widget to the top of the screen.

347

b Moves the widget to the bottom of the screen.

348

l Moves the widget to the left of the screen.

349

r Moves the widget to the right of the screen.

350

c Centers the widget between the left and

351

right of the window.

352

C Centers the widget between the top and

353

bottom of the window.

354

Escape Returns the widget to it's original position.

355

Return Exits the function and leaves the widget

356

where it was.

357

.fi

358

.RE

359

.RS 3

360

.LP

361

Keypad means that if the keyboard you are using has a keypad, then the

362

Num-Lock light has to be on in order to use the keys as listed. (The

363

numeric keys at the top of the keyboard will work as well.)

364

.LP

365

void drawCDKScroll (CDKSCROLL *\f2scroll\f1, boolean \f2box\f1);

366

.RS 3

367

This function draws the scroll widget on the screen. The \f2box\f1 option

368

draws the widget with or without a box.

369

.RE

370

371

void eraseCDKScroll (CDKSCROLL *\f2scroll\f1);

372

.RS 3

373

This function removes the widget from the screen. This does \f4NOT\f1 destroy

374

the widget.

375

.RE

376

377

void destroyCDKScroll (CDKSCROLL *\f2scroll\f1);

378

.RS 3

379

This function removes the widget from the screen and frees up any memory the

380

object may be using.

381

.RE

382

383

void setCDKScrollPreProcess (CDKSCROLL *\f2scroll\f1, PROCESSFN \f2function\f1, void *\f2data\f1);

384

.RS 3

385

This function allows the user to have the widget call a function after a key

386

is hit and before the key is applied to the widget. The parameter \f2function\f1

387

if of type \f4PROCESSFN\f1. The parameter \f2data\f1 is a pointer to

388

\f4void\f1. To learn more about pre-processing read the \f4cdk_process\f1

389

manual page.

390

.RE

391

392

void setCDKScrollPostProcess (CDKSCROLL *\f2scroll\f1, PROCESSFN \f2function\f1, void *\f2data\f1);

393

.RS 3

394

This function allows the user to have the widget call a function after the

395

key has been applied to the widget. The parameter \f2function\f1 if of type

396

\f4PROCESSFN\f1. The parameter \f2data\f1 is a pointer to \f4void\f1. To

397

learn more about post-processing read the \f4cdk_process\f1 manual page.

398

.RE

399

400

void bindCDKObject (EObjectType \f2widgetType\f1, void *\f2object\f1, char \f2key\f1, BINDFN \f2function\f1, void *\f2data\f1);

401

.RS 3

402

This function allows the user to create special key bindings. The

403

\f2widgetType\f1 parameter is a defined type which states what Cdk object

404

type is being used. To learn more about the type \f4EObjectType\f1 read the

405

\f4cdk_binding\f1 manual page. The \f2object\f1 parameter is the pointer to

406

the widget object. The \f2key\f1 is the character to bind. The \f2function\f1

407

is the function type. To learn more about the key binding callback function

408

types read the \f4cdk_binding\f1 manual page. The last parameter \f2data\f1

409

is a pointer to any data that needs to get passed to the callback function.

410

.RE

411

.SH KEY BINDINGS

412

When the widget is activated there are several default key bindings which will

413

help the user enter or manipulate the information quickly. The following table

414

outlines the keys and their actions for this widget.

415

.LP

416

.nf

417

.RS 3

418

\f2Key Action\f1

419

Left Arrow Shifts the whole list left one character.

420

Right Arrow Shifts the whole list right one character.

421

Up Arrow Selects the next item up in the list.

422

Down Arrow Selects the next item down in the list.

423

Prev Page Moves one page backwards.

424

Ctrl-B Moves one page backwards.

425

Next Page Moves one page forwards.

426

Ctrl-F Moves one page forwards.

427

g Moves to the first element in the list.

428

1 Moves to the first element in the list.

429

G Moves to the last element in the list.

430

$ Shifts the whole list to the far right.

431

| Shifts the whole list to the far left.

432

Return Exits the widget and returns an integer

433

value representing which item was

434

selected. This also sets the structure

435

member \f4exitType\f1 in the widget pointer

436

to the value of \f4vNORMAL\f1.

437

Tab Exits the widget and returns an integer

438

value representing which item was

439

selected. This also sets the structure

440

member \f4exitType\f1 in the widget

441

pointer to the value of \f4vNORMAL\f1.

442

Escape Exits the widget and returns -1. This

443

also sets the structure member

444

\f4exitType\f1 in the widget pointer to

445

the value of \f4vESCAPE_HIT\f1.

446

Ctrl-L Refreshes the screen.

447

.RE

448

.fi

449

.SH SEE ALSO

450

.BR cdk (3),

451

.BR cdk_binding (3),

452

.BR cdk_display (3),

453

.BR cdk_screen (3)

454

.SH NOTES

455

.PP

456

The header file \f4<cdk.h>\f1 automatically includes the header files

457

\f4<curses.h>\f1, \f4<stdlib.h>\f1, \f4<string.h>\f1, \f4<ctype.h>\f1,

458

\f4<unistd.h>\f1, \f4<dirent.h>\f1, \f4<time.h>\f1, \f4<errno.h>\f1,

459

\f4<pwd.h>\f1, \f4<grp.h>\f1, \f4<sys/stat.h>\f1, and \f4<sys/types.h>\f1.

460

The \f4<curses.h>\f1 header file includes \f4<stdio.h>\f1 and \f4<unctrl.h>\f1.

461

.PP

462

If you have \f4Ncurses\f1 installed on your machine add -DNCURSES to the

463

compile line to include the Ncurses header files instead.

Older »