1 /** @file 2 FormDiplay protocol to show Form 3 4 Copyright (c) 2013 - 2016, Intel Corporation. All rights reserved.<BR> 5 This program and the accompanying materials are licensed and made available under 6 the terms and conditions of the BSD License that accompanies this distribution. 7 The full text of the license may be found at 8 http://opensource.org/licenses/bsd-license.php. 9 10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 12 13 **/ 14 15 #ifndef __FORM_DISPLAY_H__ 16 #define __FORM_DISPLAY_H__ 17 18 19 #include <Library/UefiBootServicesTableLib.h> 20 #include <Library/DebugLib.h> 21 #include <Library/BaseMemoryLib.h> 22 #include <Library/BaseLib.h> 23 #include <Library/HiiLib.h> 24 #include <Library/MemoryAllocationLib.h> 25 #include <Library/PrintLib.h> 26 #include <Library/CustomizedDisplayLib.h> 27 28 #include <Protocol/FormBrowserEx2.h> 29 #include <Protocol/SimpleTextIn.h> 30 #include <Protocol/DisplayProtocol.h> 31 32 #include <Guid/MdeModuleHii.h> 33 34 // 35 // This is the generated header file which includes whatever needs to be exported (strings + IFR) 36 // 37 extern UINT8 DisplayEngineStrings[]; 38 extern EFI_SCREEN_DESCRIPTOR gStatementDimensions; 39 extern USER_INPUT *gUserInput; 40 extern FORM_DISPLAY_ENGINE_FORM *gFormData; 41 extern EFI_HII_HANDLE gHiiHandle; 42 extern UINT16 gDirection; 43 extern LIST_ENTRY gMenuOption; 44 45 // 46 // Browser Global Strings 47 // 48 extern CHAR16 *gSaveFailed; 49 extern CHAR16 *gPromptForData; 50 extern CHAR16 *gPromptForPassword; 51 extern CHAR16 *gPromptForNewPassword; 52 extern CHAR16 *gConfirmPassword; 53 extern CHAR16 *gConfirmError; 54 extern CHAR16 *gPassowordInvalid; 55 extern CHAR16 *gPressEnter; 56 extern CHAR16 *gEmptyString; 57 extern CHAR16 *gMiniString; 58 extern CHAR16 *gOptionMismatch; 59 extern CHAR16 *gFormSuppress; 60 extern CHAR16 *gProtocolNotFound; 61 extern CHAR16 *gPasswordUnsupported; 62 63 extern CHAR16 gPromptBlockWidth; 64 extern CHAR16 gOptionBlockWidth; 65 extern CHAR16 gHelpBlockWidth; 66 extern CHAR16 *mUnknownString; 67 extern BOOLEAN gMisMatch; 68 69 // 70 // Screen definitions 71 // 72 73 #define LEFT_SKIPPED_COLUMNS 3 74 #define SCROLL_ARROW_HEIGHT 1 75 #define POPUP_PAD_SPACE_COUNT 5 76 #define POPUP_FRAME_WIDTH 2 77 78 #define UPPER_LOWER_CASE_OFFSET 0x20 79 80 // 81 // Display definitions 82 // 83 #define LEFT_ONEOF_DELIMITER L'<' 84 #define RIGHT_ONEOF_DELIMITER L'>' 85 86 #define LEFT_NUMERIC_DELIMITER L'[' 87 #define RIGHT_NUMERIC_DELIMITER L']' 88 89 #define LEFT_CHECKBOX_DELIMITER L'[' 90 #define RIGHT_CHECKBOX_DELIMITER L']' 91 92 #define CHECK_ON L'X' 93 #define CHECK_OFF L' ' 94 95 #define TIME_SEPARATOR L':' 96 #define DATE_SEPARATOR L'/' 97 98 #define SUBTITLE_INDENT 2 99 100 // 101 // This is the Input Error Message 102 // 103 #define INPUT_ERROR 1 104 105 // 106 // This is the NV RAM update required Message 107 // 108 #define NV_UPDATE_REQUIRED 2 109 // 110 // Time definitions 111 // 112 #define ONE_SECOND 10000000 113 114 // 115 // It take 23 characters including the NULL to print a 64 bits number with "[" and "]". 116 // pow(2, 64) = [18446744073709551616] 117 // with extra '-' flat, set the width to 24. 118 // 119 #define MAX_NUMERIC_INPUT_WIDTH 24 120 121 #define EFI_HII_EXPRESSION_INCONSISTENT_IF 0 122 #define EFI_HII_EXPRESSION_NO_SUBMIT_IF 1 123 #define EFI_HII_EXPRESSION_GRAY_OUT_IF 2 124 #define EFI_HII_EXPRESSION_SUPPRESS_IF 3 125 #define EFI_HII_EXPRESSION_DISABLE_IF 4 126 127 // 128 // Character definitions 129 // 130 #define CHAR_SPACE 0x0020 131 132 #define FORM_DISPLAY_DRIVER_SIGNATURE SIGNATURE_32 ('F', 'D', 'D', 'V') 133 typedef struct { 134 UINT32 Signature; 135 136 EFI_HANDLE Handle; 137 138 // 139 // Produced protocol 140 // 141 EDKII_FORM_DISPLAY_ENGINE_PROTOCOL FromDisplayProt; 142 } FORM_DISPLAY_DRIVER_PRIVATE_DATA; 143 144 145 typedef enum { 146 UiNoOperation, 147 UiSelect, 148 UiUp, 149 UiDown, 150 UiLeft, 151 UiRight, 152 UiReset, 153 UiPrevious, 154 UiPageUp, 155 UiPageDown, 156 UiHotKey, 157 UiMaxOperation 158 } UI_SCREEN_OPERATION; 159 160 typedef enum { 161 CfInitialization, 162 CfCheckSelection, 163 CfRepaint, 164 CfRefreshHighLight, 165 CfUpdateHelpString, 166 CfPrepareToReadKey, 167 CfReadKey, 168 CfScreenOperation, 169 CfUiSelect, 170 CfUiReset, 171 CfUiLeft, 172 CfUiRight, 173 CfUiUp, 174 CfUiPageUp, 175 CfUiPageDown, 176 CfUiDown, 177 CfUiNoOperation, 178 CfExit, 179 CfUiHotKey, 180 CfMaxControlFlag 181 } UI_CONTROL_FLAG; 182 183 typedef enum { 184 UIEventNone, 185 UIEventKey, 186 UIEventTimeOut, 187 UIEventDriver 188 } UI_EVENT_TYPE; 189 190 typedef struct { 191 UINT16 ScanCode; 192 UI_SCREEN_OPERATION ScreenOperation; 193 } SCAN_CODE_TO_SCREEN_OPERATION; 194 195 typedef struct { 196 UI_SCREEN_OPERATION ScreenOperation; 197 UI_CONTROL_FLAG ControlFlag; 198 } SCREEN_OPERATION_T0_CONTROL_FLAG; 199 200 typedef struct { 201 EFI_HII_HANDLE HiiHandle; 202 UINT16 FormId; 203 204 // 205 // Info for the highlight question. 206 // HLT means highlight 207 // 208 // If one statement has questionid, save questionid info to find the question. 209 // If one statement not has questionid info, save the opcode info to find the 210 // statement. If more than one statement has same opcode in one form(just like 211 // empty subtitle info may has more than one info one form), also use Index 212 // info to find the statement. 213 // 214 EFI_QUESTION_ID HLTQuestionId; 215 EFI_IFR_OP_HEADER *HLTOpCode; 216 UINTN HLTIndex; 217 UINTN HLTSequence; 218 219 // 220 // Info for the top of screen question. 221 // TOS means Top Of Screen 222 // 223 EFI_QUESTION_ID TOSQuestionId; 224 EFI_IFR_OP_HEADER *TOSOpCode; 225 UINTN TOSIndex; 226 227 UINT16 SkipValue; 228 } DISPLAY_HIGHLIGHT_MENU_INFO; 229 230 typedef struct { 231 EFI_EVENT SyncEvent; 232 UINT8 *TimeOut; 233 CHAR16 *ErrorInfo; 234 } WARNING_IF_CONTEXT; 235 236 #define UI_MENU_OPTION_SIGNATURE SIGNATURE_32 ('u', 'i', 'm', 'm') 237 238 typedef struct { 239 UINTN Signature; 240 LIST_ENTRY Link; 241 242 EFI_HII_HANDLE Handle; 243 FORM_DISPLAY_ENGINE_STATEMENT *ThisTag; 244 UINT16 EntryNumber; 245 246 UINTN Row; 247 UINTN Col; 248 UINTN OptCol; 249 CHAR16 *Description; 250 UINTN Skip; // Number of lines 251 252 // 253 // Display item sequence for date/time 254 // Date: Month/Day/Year 255 // Sequence: 0 1 2 256 // 257 // Time: Hour : Minute : Second 258 // Sequence: 0 1 2 259 // 260 // 261 UINTN Sequence; 262 263 BOOLEAN GrayOut; 264 BOOLEAN ReadOnly; 265 266 // 267 // Whether user could change value of this item 268 // 269 BOOLEAN IsQuestion; 270 BOOLEAN NestInStatement; 271 } UI_MENU_OPTION; 272 273 #define MENU_OPTION_FROM_LINK(a) CR (a, UI_MENU_OPTION, Link, UI_MENU_OPTION_SIGNATURE) 274 275 /** 276 Print Question Value according to it's storage width and display attributes. 277 278 @param Question The Question to be printed. 279 @param FormattedNumber Buffer for output string. 280 @param BufferSize The FormattedNumber buffer size in bytes. 281 282 @retval EFI_SUCCESS Print success. 283 @retval EFI_BUFFER_TOO_SMALL Buffer size is not enough for formatted number. 284 285 **/ 286 EFI_STATUS 287 PrintFormattedNumber ( 288 IN FORM_DISPLAY_ENGINE_STATEMENT *Question, 289 IN OUT CHAR16 *FormattedNumber, 290 IN UINTN BufferSize 291 ); 292 293 /** 294 Set value of a data element in an Array by its Index. 295 296 @param Array The data array. 297 @param Type Type of the data in this array. 298 @param Index Zero based index for data in this array. 299 @param Value The value to be set. 300 301 **/ 302 VOID 303 SetArrayData ( 304 IN VOID *Array, 305 IN UINT8 Type, 306 IN UINTN Index, 307 IN UINT64 Value 308 ); 309 310 /** 311 Return data element in an Array by its Index. 312 313 @param Array The data array. 314 @param Type Type of the data in this array. 315 @param Index Zero based index for data in this array. 316 317 @retval Value The data to be returned 318 319 **/ 320 UINT64 321 GetArrayData ( 322 IN VOID *Array, 323 IN UINT8 Type, 324 IN UINTN Index 325 ); 326 327 /** 328 Search an Option of a Question by its value. 329 330 @param Question The Question 331 @param OptionValue Value for Option to be searched. 332 333 @retval Pointer Pointer to the found Option. 334 @retval NULL Option not found. 335 336 **/ 337 DISPLAY_QUESTION_OPTION * 338 ValueToOption ( 339 IN FORM_DISPLAY_ENGINE_STATEMENT *Question, 340 IN EFI_HII_VALUE *OptionValue 341 ); 342 343 /** 344 Compare two Hii value. 345 346 @param Value1 Expression value to compare on left-hand. 347 @param Value2 Expression value to compare on right-hand. 348 @param Result Return value after compare. 349 retval 0 Two operators equal. 350 return Positive value if Value1 is greater than Value2. 351 retval Negative value if Value1 is less than Value2. 352 @param HiiHandle Only required for string compare. 353 354 @retval other Could not perform compare on two values. 355 @retval EFI_SUCCESS Compare the value success. 356 357 **/ 358 EFI_STATUS 359 CompareHiiValue ( 360 IN EFI_HII_VALUE *Value1, 361 IN EFI_HII_VALUE *Value2, 362 OUT INTN *Result, 363 IN EFI_HII_HANDLE HiiHandle OPTIONAL 364 ); 365 366 /** 367 Draw a pop up windows based on the dimension, number of lines and 368 strings specified. 369 370 @param RequestedWidth The width of the pop-up. 371 @param NumberOfLines The number of lines. 372 @param ... A series of text strings that displayed in the pop-up. 373 374 **/ 375 VOID 376 EFIAPI 377 CreateMultiStringPopUp ( 378 IN UINTN RequestedWidth, 379 IN UINTN NumberOfLines, 380 ... 381 ); 382 383 /** 384 Will copy LineWidth amount of a string in the OutputString buffer and return the 385 number of CHAR16 characters that were copied into the OutputString buffer. 386 The output string format is: 387 Glyph Info + String info + '\0'. 388 389 In the code, it deals \r,\n,\r\n same as \n\r, also it not process the \r or \g. 390 391 @param InputString String description for this option. 392 @param LineWidth Width of the desired string to extract in CHAR16 393 characters 394 @param GlyphWidth The glyph width of the begin of the char in the string. 395 @param Index Where in InputString to start the copy process 396 @param OutputString Buffer to copy the string into 397 398 @return Returns the number of CHAR16 characters that were copied into the OutputString 399 buffer, include extra glyph info and '\0' info. 400 401 **/ 402 UINT16 403 GetLineByWidth ( 404 IN CHAR16 *InputString, 405 IN UINT16 LineWidth, 406 IN OUT UINT16 *GlyphWidth, 407 IN OUT UINTN *Index, 408 OUT CHAR16 **OutputString 409 ); 410 411 412 /** 413 Get the string based on the StringId and HII Package List Handle. 414 415 @param Token The String's ID. 416 @param HiiHandle The Hii handle for this string package. 417 418 @return The output string. 419 420 **/ 421 CHAR16 * 422 GetToken ( 423 IN EFI_STRING_ID Token, 424 IN EFI_HII_HANDLE HiiHandle 425 ); 426 427 /** 428 Count the storage space of a Unicode string. 429 430 This function handles the Unicode string with NARROW_CHAR 431 and WIDE_CHAR control characters. NARROW_HCAR and WIDE_CHAR 432 does not count in the resultant output. If a WIDE_CHAR is 433 hit, then 2 Unicode character will consume an output storage 434 space with size of CHAR16 till a NARROW_CHAR is hit. 435 436 If String is NULL, then ASSERT (). 437 438 @param String The input string to be counted. 439 440 @return Storage space for the input string. 441 442 **/ 443 UINTN 444 GetStringWidth ( 445 IN CHAR16 *String 446 ); 447 448 /** 449 This routine reads a numeric value from the user input. 450 451 @param MenuOption Pointer to the current input menu. 452 453 @retval EFI_SUCCESS If numerical input is read successfully 454 @retval EFI_DEVICE_ERROR If operation fails 455 456 **/ 457 EFI_STATUS 458 GetNumericInput ( 459 IN UI_MENU_OPTION *MenuOption 460 ); 461 462 /** 463 Get string or password input from user. 464 465 @param MenuOption Pointer to the current input menu. 466 @param Prompt The prompt string shown on popup window. 467 @param StringPtr Old user input and destination for use input string. 468 469 @retval EFI_SUCCESS If string input is read successfully 470 @retval EFI_DEVICE_ERROR If operation fails 471 472 **/ 473 EFI_STATUS 474 ReadString ( 475 IN UI_MENU_OPTION *MenuOption, 476 IN CHAR16 *Prompt, 477 IN OUT CHAR16 *StringPtr 478 ); 479 480 /** 481 Draw a pop up windows based on the dimension, number of lines and 482 strings specified. 483 484 @param RequestedWidth The width of the pop-up. 485 @param NumberOfLines The number of lines. 486 @param Marker The variable argument list for the list of string to be printed. 487 488 **/ 489 VOID 490 CreateSharedPopUp ( 491 IN UINTN RequestedWidth, 492 IN UINTN NumberOfLines, 493 IN VA_LIST Marker 494 ); 495 496 /** 497 Wait for a key to be pressed by user. 498 499 @param Key The key which is pressed by user. 500 501 @retval EFI_SUCCESS The function always completed successfully. 502 503 **/ 504 EFI_STATUS 505 WaitForKeyStroke ( 506 OUT EFI_INPUT_KEY *Key 507 ); 508 509 /** 510 Get selection for OneOf and OrderedList (Left/Right will be ignored). 511 512 @param MenuOption Pointer to the current input menu. 513 514 @retval EFI_SUCCESS If Option input is processed successfully 515 @retval EFI_DEVICE_ERROR If operation fails 516 517 **/ 518 EFI_STATUS 519 GetSelectionInputPopUp ( 520 IN UI_MENU_OPTION *MenuOption 521 ); 522 523 /** 524 Process the help string: Split StringPtr to several lines of strings stored in 525 FormattedString and the glyph width of each line cannot exceed gHelpBlockWidth. 526 527 @param StringPtr The entire help string. 528 @param FormattedString The oupput formatted string. 529 @param EachLineWidth The max string length of each line in the formatted string. 530 @param RowCount TRUE: if Question is selected. 531 532 **/ 533 UINTN 534 ProcessHelpString ( 535 IN CHAR16 *StringPtr, 536 OUT CHAR16 **FormattedString, 537 OUT UINT16 *EachLineWidth, 538 IN UINTN RowCount 539 ); 540 541 /** 542 Process a Question's Option (whether selected or un-selected). 543 544 @param MenuOption The MenuOption for this Question. 545 @param Selected TRUE: if Question is selected. 546 @param OptionString Pointer of the Option String to be displayed. 547 @param SkipErrorValue Whether need to return when value without option for it. 548 549 @retval EFI_SUCCESS Question Option process success. 550 @retval Other Question Option process fail. 551 552 **/ 553 EFI_STATUS 554 ProcessOptions ( 555 IN UI_MENU_OPTION *MenuOption, 556 IN BOOLEAN Selected, 557 OUT CHAR16 **OptionString, 558 IN BOOLEAN SkipErrorValue 559 ); 560 561 /** 562 Set Buffer to Value for Size bytes. 563 564 @param Buffer Memory to set. 565 @param Size Number of bytes to set 566 @param Value Value of the set operation. 567 568 **/ 569 VOID 570 SetUnicodeMem ( 571 IN VOID *Buffer, 572 IN UINTN Size, 573 IN CHAR16 Value 574 ); 575 576 /** 577 Display one form, and return user input. 578 579 @param FormData Form Data to be shown. 580 @param UserInputData User input data. 581 582 @retval EFI_SUCCESS Form Data is shown, and user input is got. 583 **/ 584 EFI_STATUS 585 EFIAPI 586 FormDisplay ( 587 IN FORM_DISPLAY_ENGINE_FORM *FormData, 588 OUT USER_INPUT *UserInputData 589 ); 590 591 /** 592 Clear Screen to the initial state. 593 **/ 594 VOID 595 EFIAPI 596 DriverClearDisplayPage ( 597 VOID 598 ); 599 600 /** 601 Exit Display and Clear Screen to the original state. 602 603 **/ 604 VOID 605 EFIAPI 606 ExitDisplay ( 607 VOID 608 ); 609 610 /** 611 Process nothing. 612 613 @param Event The Event need to be process 614 @param Context The context of the event. 615 616 **/ 617 VOID 618 EFIAPI 619 EmptyEventProcess ( 620 IN EFI_EVENT Event, 621 IN VOID *Context 622 ); 623 624 /** 625 Process for the refresh interval statement. 626 627 @param Event The Event need to be process 628 @param Context The context of the event. 629 630 **/ 631 VOID 632 EFIAPI 633 RefreshTimeOutProcess ( 634 IN EFI_EVENT Event, 635 IN VOID *Context 636 ); 637 638 /** 639 Record the highlight menu and top of screen menu info. 640 641 @param Highlight The menu opton which is highlight. 642 @param TopOfScreen The menu opton which is at the top of the form. 643 @param SkipValue The skip line info for the top of screen menu. 644 645 **/ 646 VOID 647 UpdateHighlightMenuInfo ( 648 IN LIST_ENTRY *Highlight, 649 IN LIST_ENTRY *TopOfScreen, 650 IN UINTN SkipValue 651 ); 652 653 #endif 654